mirror of
https://github.com/zadam/trilium.git
synced 2025-10-31 03:29:02 +01:00
122 lines
7.4 KiB
HTML
122 lines
7.4 KiB
HTML
<!DOCTYPE html>
|
|
<html lang="en">
|
|
<head>
|
|
<meta charset="utf-8">
|
|
|
|
|
|
<meta name="viewport" content="width=device-width, initial-scale=1">
|
|
|
|
<link rel="shortcut icon" href="./favicon.ico">
|
|
|
|
<script src="./assets/v0.63.6/app-dist/share.js"></script>
|
|
|
|
<link href="./assets/v0.63.6/libraries/normalize.min.css" rel="stylesheet">
|
|
<link href="./assets/v0.63.6/stylesheets/share.css" rel="stylesheet">
|
|
|
|
|
|
<link href="./assets/v0.63.6/libraries/ckeditor/ckeditor-content.css" rel="stylesheet">
|
|
|
|
|
|
|
|
|
|
|
|
<title>Internationalisation</title>
|
|
</head>
|
|
<body data-note-id="hkrBX8KE1HQl" data-ancestor-note-id="4yYHqKbLovVX">
|
|
<div id="layout">
|
|
<div id="main">
|
|
|
|
<nav id="parentLink">
|
|
parent: <a href="4yYHqKbLovVX.html"
|
|
class="type-text">Developer's Guide</a>
|
|
</nav>
|
|
|
|
|
|
<h1 id="title">Internationalisation</h1>
|
|
|
|
|
|
|
|
|
|
<div id="content" class="type-text ck-content">
|
|
<p>During the initial development of Trilium Notes, internationalisation was not considered as it was meant to be an English-only product.</p><p>As the application and the user base grows, it makes sense to be able to reach out as many people as possible by providing translations in their native language.</p><p>The library used is <a href="https://www.i18next.com/">i18next</a>.</p><h2>What has been implemented so far</h2><ul class="todo-list"><li><label class="todo-list__label"><input type="checkbox" checked="checked" disabled="disabled"><span class="todo-list__label__description">Client component-level translations: <a href="https://github.com/TriliumNext/Notes/pull/248/files">#248</a></span></label></li><li><label class="todo-list__label"><input type="checkbox" disabled="disabled"><span class="todo-list__label__description">Client template-level translations</span></label></li><li><label class="todo-list__label"><input type="checkbox" disabled="disabled"><span class="todo-list__label__description">Server-side translations</span></label></li><li><label class="todo-list__label"><input type="checkbox" disabled="disabled"><span class="todo-list__label__description">Electron translations</span></label></li><li><label class="todo-list__label"><input type="checkbox" disabled="disabled"><span class="todo-list__label__description">Allowing the user to switch the language via options</span></label></li><li><label class="todo-list__label"><input type="checkbox" disabled="disabled"><span class="todo-list__label__description">Integrate with a translation service</span></label></li></ul><h2>Where are the translations?</h2><p>The translations are formatted as JSON files and they are located in <code>src/public/translations</code>. For every supported locale, there is a subdirectory in which there is a <code>translation.json</code> file (e.g. <code>src/public/translations/en/translation.json</code>).</p><h3>Message keys</h3><p>One important aspect is the fact that we are using a key-based approach. This means that each message is identified by an ID rather than a natural-language message (such as the default approach in gettext).</p><p>The key-based approach allows a hierarchical structure. For example, a key of <code>about.title</code> would be added in <code>translation.json</code> as follows:</p><pre><code class="language-application-json">{
|
|
"about": {
|
|
"title": "About TriliumNext Notes"
|
|
}
|
|
} </code></pre><h3>Adding a new locale</h3><p>To add a new locale, go to <code>src/public/translations</code> with your favorite text editor and copy the <code>en</code> directory.</p><p>Rename the copy to the ISO code (e.g. <code>fr</code>, <code>ro</code>) of the language being translated.</p><p>Translations with a country-language combination, using their corresponding ISO code (e.g. <code>fr_FR</code>, <code>fr_BE</code>), has not been tested yet.</p><h3>Changing the language</h3><p>Since the internationalisation process is in its early stages, there is no user-facing way to switch the language.</p><p>To change the language manually, edit <code>src/public/app/services/i18n.js</code> and look for the line containing <code>lng: "en"</code>. Replace <code>en</code> with the desired language code (from the ones available in <code>src/public/translations</code>).</p><h2>Recommendations</h2><ul><li>Use hierarchy whenever appropriate, try to group the messages by:<ul><li>Modals (e.g. <code>about.foo</code>, <code>jump_to_note.foo</code>)</li></ul></li><li>Don't duplicate messages that are very widely used.<ul><li>One such example is <code>aria-label="Close"</code> which should go to a single message such as <code>modal.close</code> instead of being duplicated in every modal.</li></ul></li><li>On the other hand, don't overly generalise messages. A <code>close</code> message that is used whenever the “Close” word is encountered is not a good approach since it can potentially cause issues due to lack of context.</li><li>Use <a href="https://www.i18next.com/translation-function/interpolation">variable interpolation</a> whenever appropriate.<ul><li>If you see multiple messages joined together only to apply add a variable such as a user-inputted value, try to join those messages together into a single message containing a variable.</li><li>So instead of <code>“Number of updates: “ + numUpdates + “.”</code> use <code>$(t("number_updates", { numUpdates }))</code> where the message translation would appear as <code>Number of updates: {{numUpdates}}.</code></li></ul></li></ul><h2>Client-side translations</h2><h3>Component-level translations</h3><p>Most of the client translations are present in the various widgets and layouts.</p><p>Translation support has to be added manually for every file.</p><p>The first step is to add the translation import with a relative import. For example, if we are in the <code>src/public/app/widgets/dialogs</code> directory, the import would look as follows:</p><pre><code class="language-application-javascript-env-frontend">import { t } from "../../services/i18n.js";</code></pre><p>Afterwards, simply replace the hard-coded message with:</p><pre><code class="language-application-javascript-env-frontend">${t("msgid")}</code></pre><p>where <code>msgid</code> is the key of the message being translated.</p><h3>Template-level translations</h3><p>Templates are <code>.ejs</code> files present in <code>src/views</code>, these are used to prepare the root layout for desktop, mobile applications as well as setup (onboarding) and the shared notes view.</p><p>Due to using a different approach, it is not possible yet to translate those files.</p><h2>Server-side translations</h2><p>Currently the server-side messages are not translatable. They will be added as a separate step.</p>
|
|
</div>
|
|
|
|
|
|
|
|
</div>
|
|
|
|
|
|
<button id="toggleMenuButton"></button>
|
|
|
|
<nav id="menu">
|
|
|
|
<p>
|
|
|
|
|
|
|
|
<a class="type-text" href="4yYHqKbLovVX.html">Developer's Guide</a>
|
|
|
|
</p>
|
|
|
|
|
|
<ul>
|
|
|
|
<li>
|
|
|
|
<p>
|
|
|
|
|
|
|
|
<strong>Internationalisation</strong>
|
|
|
|
</p>
|
|
|
|
|
|
|
|
</li>
|
|
|
|
<li>
|
|
|
|
<p>
|
|
|
|
|
|
|
|
<a class="type-text" href="VS22Hq5PBFNf.html">Dependency Management</a>
|
|
|
|
</p>
|
|
|
|
|
|
<ul>
|
|
|
|
<li>
|
|
|
|
<p>
|
|
|
|
|
|
|
|
<a class="type-text" href="QXCi6Y1SYulw.html">Adding a new client library</a>
|
|
|
|
</p>
|
|
|
|
|
|
|
|
</li>
|
|
|
|
</ul>
|
|
|
|
|
|
</li>
|
|
|
|
</ul>
|
|
|
|
|
|
</nav>
|
|
|
|
</div>
|
|
</body>
|
|
</html>
|