mirror of
https://github.com/zadam/trilium.git
synced 2025-11-01 10:55:55 +01:00
docs: Deploy first documentation
This commit is contained in:
Elian Doran
126
docs/share/4yYHqKbLovVX
Normal file
126
docs/share/4yYHqKbLovVX
Normal file
@@ -0,0 +1,126 @@
|
||||
<!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>Developer's Guide</title>
|
||||
</head>
|
||||
<body data-note-id="4yYHqKbLovVX" data-ancestor-note-id="4yYHqKbLovVX">
|
||||
<div id="layout">
|
||||
<div id="main">
|
||||
|
||||
|
||||
<h1 id="title">Developer's Guide</h1>
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
<nav id="childLinks" class="grid">
|
||||
|
||||
|
||||
<ul>
|
||||
|
||||
<li>
|
||||
<a href="./hkrBX8KE1HQl"
|
||||
class="type-text">Internationalisation</a>
|
||||
</li>
|
||||
|
||||
<li>
|
||||
<a href="./VS22Hq5PBFNf"
|
||||
class="type-text">Dependency Management</a>
|
||||
</li>
|
||||
|
||||
</ul>
|
||||
</nav>
|
||||
|
||||
</div>
|
||||
|
||||
|
||||
<button id="toggleMenuButton"></button>
|
||||
|
||||
<nav id="menu">
|
||||
|
||||
<p>
|
||||
|
||||
|
||||
|
||||
<strong>Developer's Guide</strong>
|
||||
|
||||
</p>
|
||||
|
||||
|
||||
<ul>
|
||||
|
||||
<li>
|
||||
|
||||
<p>
|
||||
|
||||
|
||||
|
||||
<a class="type-text" href="./hkrBX8KE1HQl">Internationalisation</a>
|
||||
|
||||
</p>
|
||||
|
||||
|
||||
|
||||
</li>
|
||||
|
||||
<li>
|
||||
|
||||
<p>
|
||||
|
||||
|
||||
|
||||
<a class="type-text" href="./VS22Hq5PBFNf">Dependency Management</a>
|
||||
|
||||
</p>
|
||||
|
||||
|
||||
<ul>
|
||||
|
||||
<li>
|
||||
|
||||
<p>
|
||||
|
||||
|
||||
|
||||
<a class="type-text" href="./QXCi6Y1SYulw">Adding a new client library</a>
|
||||
|
||||
</p>
|
||||
|
||||
|
||||
|
||||
</li>
|
||||
|
||||
</ul>
|
||||
|
||||
|
||||
</li>
|
||||
|
||||
</ul>
|
||||
|
||||
|
||||
</nav>
|
||||
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
165
docs/share/QXCi6Y1SYulw
Normal file
165
docs/share/QXCi6Y1SYulw
Normal file
@@ -0,0 +1,165 @@
|
||||
<!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>Adding a new client library</title>
|
||||
</head>
|
||||
<body data-note-id="QXCi6Y1SYulw" data-ancestor-note-id="4yYHqKbLovVX">
|
||||
<div id="layout">
|
||||
<div id="main">
|
||||
|
||||
<nav id="parentLink">
|
||||
parent: <a href="VS22Hq5PBFNf"
|
||||
class="type-text">Dependency Management</a>
|
||||
</nav>
|
||||
|
||||
|
||||
<h1 id="title">Adding a new client library</h1>
|
||||
|
||||
|
||||
|
||||
|
||||
<div id="content" class="type-text ck-content">
|
||||
<p>In the past some libraries have been copy-pasted (and adapted if needed) to the repository. However, new libraries must be obtained exclusively through npm.</p><p>The first step is to install the desired library. As an example we are going to install <code>i18next</code>:</p><pre><code class="language-text-plain">npm i i18next</code></pre><h3>Step 1. Understanding the structure of the import</h3><p>After installing the dependency, it's important to know how it's structured. You can do this by looking at the directory structure of the newly imported dependency:</p><pre><code class="language-text-plain">$ tree node_modules/i18next
|
||||
node_modules/i18next
|
||||
├── dist
|
||||
│ ├── cjs
|
||||
│ │ └── i18next.js
|
||||
│ ├── esm
|
||||
│ │ ├── i18next.bundled.js
|
||||
│ │ ├── i18next.js
|
||||
│ │ └── package.json
|
||||
│ └── umd
|
||||
│ ├── i18next.js
|
||||
│ └── i18next.min.js
|
||||
├── i18next.js
|
||||
├── i18next.min.js
|
||||
├── index.d.mts
|
||||
├── index.d.ts
|
||||
├── index.js
|
||||
├── index.v4.d.ts
|
||||
├── LICENSE
|
||||
├── package.json
|
||||
├── README.md
|
||||
└── typescript
|
||||
├── helpers.d.ts
|
||||
├── options.d.ts
|
||||
├── t.d.ts
|
||||
└── t.v4.d.ts</code></pre><p>Generally you should be looking for a <code>.min.js</code> file. Note that the <code>esm</code> and <code>cjs</code> variants generally don't work, we are looking for the classic, no module dependency.</p><h3>Step 2. Exposing the library from the server</h3><p>The library must be delivered by the server and this is done via <code>src/routes/assets.ts</code>. In the <code>register</code> function, add a new entry near the bottom of the function:</p><pre><code class="language-application-javascript-env-frontend">app.use(`/${assetPath}/node_modules/i18next/`, persistentCacheStatic(path.join(srcRoot, "..", 'node_modules/i18next/')));</code></pre><h3>Step 3. Adding it to the library loader</h3><p>The library loader is a client module which is in charge of downloading the library from the server and importing it. The loader is located in <code>src/public/app/services/library_loader.js</code>.</p><p>To add a new library, start by creating a constant for it, with the value pointing to the minified JS identified at the first step:</p><pre><code class="language-application-javascript-env-frontend">const I18NEXT = {
|
||||
js: [
|
||||
"node_modules/i18next/i18next.min.js"
|
||||
]
|
||||
};</code></pre><p>Then add it to the <code>export default</code> section:</p><pre><code class="language-text-x-diff"> export default {
|
||||
requireCss,
|
||||
requireLibrary,
|
||||
CKEDITOR,
|
||||
CODE_MIRROR,
|
||||
ESLINT,
|
||||
RELATION_MAP,
|
||||
PRINT_THIS,
|
||||
CALENDAR_WIDGET,
|
||||
KATEX,
|
||||
WHEEL_ZOOM,
|
||||
FORCE_GRAPH,
|
||||
MERMAID,
|
||||
EXCALIDRAW,
|
||||
- MARKJS
|
||||
+ MARKJS,
|
||||
+ I18NEXT
|
||||
}</code></pre><h3>Step 4. Using the library</h3><p>To import the library, simply use the following mechanism:</p><pre><code class="language-text-x-diff">import library_loader from "./library_loader.js";
|
||||
|
||||
await library_loader.requireLibrary(library_loader.I18NEXT);</code></pre><p>Make sure to replace <code>I18NEXT</code> with the library that was created at the previous steps.</p><p>Note that because we are not using a module management mechanism such as ES Modules or Common.js modules, the <code>requireLibrary</code> method does not actually return anything. </p><p>To benefit from the library, it must export on its own an object in <code>window</code>.</p><p>In the case of <code>i18next</code>, it sets <code>window.i18next</code> and that can be used directly:</p><pre><code class="language-text-x-diff">i18next.init({});</code></pre>
|
||||
</div>
|
||||
|
||||
|
||||
|
||||
</div>
|
||||
|
||||
|
||||
<button id="toggleMenuButton"></button>
|
||||
|
||||
<nav id="menu">
|
||||
|
||||
<p>
|
||||
|
||||
|
||||
|
||||
<a class="type-text" href="./4yYHqKbLovVX">Developer's Guide</a>
|
||||
|
||||
</p>
|
||||
|
||||
|
||||
<ul>
|
||||
|
||||
<li>
|
||||
|
||||
<p>
|
||||
|
||||
|
||||
|
||||
<a class="type-text" href="./hkrBX8KE1HQl">Internationalisation</a>
|
||||
|
||||
</p>
|
||||
|
||||
|
||||
|
||||
</li>
|
||||
|
||||
<li>
|
||||
|
||||
<p>
|
||||
|
||||
|
||||
|
||||
<a class="type-text" href="./VS22Hq5PBFNf">Dependency Management</a>
|
||||
|
||||
</p>
|
||||
|
||||
|
||||
<ul>
|
||||
|
||||
<li>
|
||||
|
||||
<p>
|
||||
|
||||
|
||||
|
||||
<strong>Adding a new client library</strong>
|
||||
|
||||
</p>
|
||||
|
||||
|
||||
|
||||
</li>
|
||||
|
||||
</ul>
|
||||
|
||||
|
||||
</li>
|
||||
|
||||
</ul>
|
||||
|
||||
|
||||
</nav>
|
||||
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
126
docs/share/VS22Hq5PBFNf
Normal file
126
docs/share/VS22Hq5PBFNf
Normal file
@@ -0,0 +1,126 @@
|
||||
<!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>Dependency Management</title>
|
||||
</head>
|
||||
<body data-note-id="VS22Hq5PBFNf" data-ancestor-note-id="4yYHqKbLovVX">
|
||||
<div id="layout">
|
||||
<div id="main">
|
||||
|
||||
<nav id="parentLink">
|
||||
parent: <a href="4yYHqKbLovVX"
|
||||
class="type-text">Developer's Guide</a>
|
||||
</nav>
|
||||
|
||||
|
||||
<h1 id="title">Dependency Management</h1>
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
<nav id="childLinks" class="grid">
|
||||
|
||||
|
||||
<ul>
|
||||
|
||||
<li>
|
||||
<a href="./QXCi6Y1SYulw"
|
||||
class="type-text">Adding a new client library</a>
|
||||
</li>
|
||||
|
||||
</ul>
|
||||
</nav>
|
||||
|
||||
</div>
|
||||
|
||||
|
||||
<button id="toggleMenuButton"></button>
|
||||
|
||||
<nav id="menu">
|
||||
|
||||
<p>
|
||||
|
||||
|
||||
|
||||
<a class="type-text" href="./4yYHqKbLovVX">Developer's Guide</a>
|
||||
|
||||
</p>
|
||||
|
||||
|
||||
<ul>
|
||||
|
||||
<li>
|
||||
|
||||
<p>
|
||||
|
||||
|
||||
|
||||
<a class="type-text" href="./hkrBX8KE1HQl">Internationalisation</a>
|
||||
|
||||
</p>
|
||||
|
||||
|
||||
|
||||
</li>
|
||||
|
||||
<li>
|
||||
|
||||
<p>
|
||||
|
||||
|
||||
|
||||
<strong>Dependency Management</strong>
|
||||
|
||||
</p>
|
||||
|
||||
|
||||
<ul>
|
||||
|
||||
<li>
|
||||
|
||||
<p>
|
||||
|
||||
|
||||
|
||||
<a class="type-text" href="./QXCi6Y1SYulw">Adding a new client library</a>
|
||||
|
||||
</p>
|
||||
|
||||
|
||||
|
||||
</li>
|
||||
|
||||
</ul>
|
||||
|
||||
|
||||
</li>
|
||||
|
||||
</ul>
|
||||
|
||||
|
||||
</nav>
|
||||
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
121
docs/share/hkrBX8KE1HQl
Normal file
121
docs/share/hkrBX8KE1HQl
Normal file
@@ -0,0 +1,121 @@
|
||||
<!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"
|
||||
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">Developer's Guide</a>
|
||||
|
||||
</p>
|
||||
|
||||
|
||||
<ul>
|
||||
|
||||
<li>
|
||||
|
||||
<p>
|
||||
|
||||
|
||||
|
||||
<strong>Internationalisation</strong>
|
||||
|
||||
</p>
|
||||
|
||||
|
||||
|
||||
</li>
|
||||
|
||||
<li>
|
||||
|
||||
<p>
|
||||
|
||||
|
||||
|
||||
<a class="type-text" href="./VS22Hq5PBFNf">Dependency Management</a>
|
||||
|
||||
</p>
|
||||
|
||||
|
||||
<ul>
|
||||
|
||||
<li>
|
||||
|
||||
<p>
|
||||
|
||||
|
||||
|
||||
<a class="type-text" href="./QXCi6Y1SYulw">Adding a new client library</a>
|
||||
|
||||
</p>
|
||||
|
||||
|
||||
|
||||
</li>
|
||||
|
||||
</ul>
|
||||
|
||||
|
||||
</li>
|
||||
|
||||
</ul>
|
||||
|
||||
|
||||
</nav>
|
||||
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
Reference in New Issue
Block a user