You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Documentation generated by <ahref="https://github.com/jsdoc3/jsdoc">JSDoc 3.5.5</a> on Sun Jan 20 2019 21:55:59 GMT+0100 (Mitteleuropäische Normalzeit) using the <ahref="https://github.com/clenemt/docdash">docdash</a> theme.
352
+
Documentation generated by <ahref="https://github.com/jsdoc3/jsdoc">JSDoc 3.6.2</a> on Sun Jun 30 2019 23:07:02 GMT+0200 (GMT+02:00) using the <ahref="https://github.com/clenemt/docdash">docdash</a> theme.
<p>A tiny library that translates your HTML file with the WebExtension translation system. It's easy to use, and you only need to modify the HTML, everything else is done by this library.</p>
<li>allows (English) HTML <ahref="#fallbacks">fallbacks</a> in the HTML file, but does not require them</li>
50
52
<li>does not translate whole document via string replacement, but relies on a proper HTML syntax</li>
51
53
<li>properly sets the <ahref="https://developer.mozilla.org/docs/Web/HTML/Global_attributes/lang">"lang" attribute</a><ahref="https://developer.mozilla.org/docs/Web/HTML/Global_attributes#attr-lang">of your HTML tag</a>, so you can e.g. use the CSS <ahref="https://developer.mozilla.org/docs/Web/CSS/:lang">lang selector</a>.</li>
54
+
<li>supports <ahref="#keeping-child-elements-in-HTML">including sub-HTML elements in translations</a>, so you do not need to use HTML replacements, but let translators dynamically place HTML elements such as links</li>
52
55
</ul>
53
-
<h2id="how-to-use-">How to use?</h2>
54
-
<p>To enable it, you just import the <ahref="Localizer.js"><code>Localizer.js</code></a>. Everything is done automatically, you do not need to call any JavaScript function or initialize something.</p>
55
-
<h3id="html-setup-for-internationalisation-i18n-">HTML setup for internationalisation (i18n)</h3>
56
+
<h2id="how-to-use%3F">How to use?</h2>
57
+
<p>To enable it, you just import the <ahref="Localizer.js"><code>Localizer.js</code></a> module. Everything is done automatically, you do not need to call any JavaScript function or initialize something.</p>
58
+
<h3id="html-setup-for-internationalisation-(i18n)">HTML setup for internationalisation (i18n)</h3>
56
59
<p>The real thing you need to do is to adjust your HTML. Actually, here is how it works:</p>
57
60
<ul>
58
61
<li>First, it always uses <ahref="https://developer.mozilla.org/docs/Learn/HTML/Howto/Use_data_attributes">data attributes</a>. To avoid clashes there, it also always uses a prefix called <code>i18n</code>.</li>
@@ -63,7 +66,7 @@ <h3 id="html-setup-for-internationalisation-i18n-">HTML setup for internationali
63
66
<p><strong>Note:</strong> Remember, that even for translating only attributes, you need to add (an empty) attribute <code>data-i18n</code> to the HTML node. Otherwise it won't be detected and translated.</p>
64
67
<h3id="fallbacks">Fallbacks</h3>
65
68
<p>As translation strings are not specified in the user-facing content, i.e. e.g. text content, but in special attributes; you can fill the "original" places of these strings with fallbacks, e.g. to the English langauge.
66
-
Taht means, you can e.g. add <code>aria-label="error message" data-i18n-aria-label="__MSG_errorMessage__"</code> and the <code>aria-label</code> will always show a valid label, even if it has not yet been loaded via JS.</p>
69
+
That means, you can e.g. add <code>aria-label="error message" data-i18n data-i18n-aria-label="__MSG_errorMessage__"</code> and the <code>aria-label</code> will always show a valid label, even if it has not (yet) been loaded via JS.</p>
67
70
<p>Note, however, this is not required and you can easily leave it away, because <ahref="https://developer.mozilla.org/docs/Mozilla/Add-ons/WebExtensions/Internationalization#Localized_string_selection">the WebExtension API includes an automatic fallback</a> and may thus fallback by itself. This of course also applies to the library here, so it will also set/replace the strings that you specify to translate, even if you e.g. hardcode translations.</p>
68
71
<h3id="example">Example</h3>
69
72
<preclass="prettyprint source lang-html"><code><!-- translate content, with hardcoded English fallback -->
@@ -74,18 +77,18 @@ <h3 id="example">Example</h3>
74
77
<!-- translate only attributes, no hardcoded fallback -->
<p>As mentioned, it uses the WebExtension translation system, so you <ahref="https://developer.mozilla.org/docs/Mozilla/Add-ons/WebExtensions/Internationalization#Providing_localized_strings_in__locales">just add the strings to translate to your <code>messages.json</code></a>.</p>
86
88
<p>For translators, it is also useful to include a small guide in your contributing guide, such as <ahref="https://github.com/TinyWebEx/common/blob/contribimprove/CONTRIBUTING.md#internationalisation-of-html-files">ours here</a>.</p>
87
89
<h3id="using-html-in-translations">Using HTML in translations</h3>
88
90
<p><strong>Important:</strong> By default you can only include plain text in your translations. HTML translations are disabled by default for security reasons!</p>
91
+
<p><em>Instead</em> of using HTML it is strongly suggested to use [the child-keeping method explained below](<ahref="#keeping-child-elements-in-HTML">including sub-HTML elements in translations</a>).</p>
89
92
<p>Whether HTML translations are enabled depends on one source code file in this repo, i.e. <ahref="replaceInnerContent.js"><code>replaceInnerContent.js</code></a>. The reason for this is that <ahref="https://github.com/mozilla/addons-linter">the linting tool</a> used on addons.mozilla.org (AMO) otherwise complains about a potential security issue if HTML translations are enabled. This results in a warning when uploading the add-on to AMO as the HTML version makes use of <code>innerHtml</code> in the JavaScript file.</p>
90
93
<p>If you want to enable HTML translations though, you need to:</p>
91
94
<ul>
@@ -95,8 +98,49 @@ <h3 id="using-html-in-translations">Using HTML in translations</h3>
"message": "!HTML! <b>This sentence is bold.</b>"
98
-
}</code></pre><p>This is also explained in short for <ahref="https://github.com/TinyWebEx/common/blob/contribimprove/CONTRIBUTING.md#using-html-in-translations">translators in the contributing guide</a>.</p>
99
-
<p><strong>Warning:</strong> If you allow/use HTML translation, note that translators could inject malicious (HTML) code then. As such, you need to take care when reviewing the translation files then. The marker <code>!HTML!</code> can help you here as you can just search for it.</p></article>
101
+
}
102
+
</code></pre>
103
+
<p>This can also explained in short for <ahref="https://github.com/TinyWebEx/common/blob/10ff5cace217841591d702408e64f1ead8c26a64/CONTRIBUTING.md#using-html-in-translations">translators in the contributing guide</a> (permalink, as I now discourage using that feature, anyway).</p>
104
+
<p><strong>Warning:</strong> If you allow/use HTML translation, note that translators could inject malicious (HTML) code then. As such, you need to take care when reviewing the translation files then. The marker <code>!HTML!</code> can help you here as you can just search for it.</p>
105
+
<h3id="keeping-child-elements-in-html">Keeping child elements in HTML</h3>
106
+
<p>By default, this module just replaces the whole text/content of an HTML tag.
107
+
A common use case is that you may need to include different sub-HTML items (children of the HTML parent) in your translation however. Especially, you may want to allow translators to adjust their position in the translation.
108
+
This is e.g. useful when you want to include links in your translation.</p>
109
+
<p>To do so, you just need to add <code>data-opt-i18n-keep-children</code> to the HTML parent that needs to be translated this way. It will then:</p>
110
+
<ul>
111
+
<li>put all HTML tags into a substitutions (<code>$1</code>, <code>$2</code>, …), which you can use to refer to your content in the translation</li>
112
+
<li>translate only the actual text content and adjust the position/ordering of the HTML tags, so they meet the translation result</li>
113
+
</ul>
114
+
<p>In the end, you e.g. can have a translation like this:</p>
Check out <a data-i18n="__MSG_linkText__" data-i18n-href="__MSG_link__" href="https://example.com">for more details</a>!
137
+
</p>
138
+
</code></pre>
139
+
<p>As you can, see in the example <code>$1</code> will be replaced with the <code>a</code> tag for the link. As you can see, obviously, you need to translate the <code>a</code> tag as usual, too, and thus you just use the same principles as usual.
140
+
It does also keep the HTML item intact and just move it, it will never be removed from the DOM and you can thus just use it as every other HTML tag.
141
+
You should also be able to nest this feature, as you want.</p>
142
+
<p><strong>Note:</strong> If you use this feature, you should make sure your translations also actually also refer to the HTML tag (the substitution) via <code>$1</code>, <code>$2</code> etc.
143
+
If they don't, the Localizer does not know where to put the HTML tag and it usually is just placed at the end. As said, it does never delete a HTML tag, so it just stays "in place" then.</p></article>
100
144
</section>
101
145
102
146
@@ -111,12 +155,14 @@ <h3 id="using-html-in-translations">Using HTML in translations</h3>
111
155
<brclass="clear">
112
156
113
157
<footer>
114
-
Documentation generated by <ahref="https://github.com/jsdoc3/jsdoc">JSDoc 3.5.5</a> on Sun Jan 20 2019 21:55:59 GMT+0100 (Mitteleuropäische Normalzeit) using the <ahref="https://github.com/clenemt/docdash">docdash</a> theme.
158
+
Documentation generated by <ahref="https://github.com/jsdoc3/jsdoc">JSDoc 3.6.2</a> on Sun Jun 30 2019 23:07:02 GMT+0200 (GMT+02:00) using the <ahref="https://github.com/clenemt/docdash">docdash</a> theme.
0 commit comments