From 0dd9e5567cd84962b1a73b5d40bbdf4da1a8f7fb Mon Sep 17 00:00:00 2001
From: Mark Sujew <mark.sujew@typefox.io>
Date: Thu, 11 Nov 2021 12:58:48 +0100
Subject: [PATCH] Add documentation on i18n (#234)

---
 src/docs/i18n.md | 85 ++++++++++++++++++++++++++++++++++++++++++++++++
 src/docs/menu.js |  4 +++
 2 files changed, 89 insertions(+)
 create mode 100644 src/docs/i18n.md

diff --git a/src/docs/i18n.md b/src/docs/i18n.md
new file mode 100644
index 00000000..4352aa0a
--- /dev/null
+++ b/src/docs/i18n.md
@@ -0,0 +1,85 @@
+---
+title: Internationalization
+---
+
+# Internationalization
+
+Theia can be localized by installing [Visual Studio Code language packs](https://code.visualstudio.com/docs/getstarted/locales). Using the `Configure Display Language` command, users of Theia can change their currently used locale.
+The framework provides additional features to enable extension developers to localize their own extensions.
+
+## Localizing your extension
+
+Let's say you have a simple string you want to present in the frontend of your application, like a custom widget that displays a goodbye message:
+
+```tsx
+render() {
+    return <span>Bye</span>
+}
+```
+
+To display this message using different locales, you can use the `nls.localize` function, imported from the `@theia/core` package:
+
+```tsx
+render() {
+    return <span>{nls.localize('bye', 'Bye')}</span>
+}
+```
+
+The first argument is a key to identify the translated value. The second argument is the default value that will be used if the user didn't change their locale. When using template expressions in the frontend, keep in mind that the `nls.localize` function allows you to format strings using the additional `args` parameter. When the `localize` function identifies placeholders in the format `{n}` where *n* represents any number, it will try to replace the placeholder with the input parameter at the appropriate position, e.g. `{0}` will be replaced by the first additional parameter, `{1}` by the second and so forth:
+
+```typescript
+nls.localize('bye-format', 'Bye {0} and {1}!', first, second);
+```
+
+The `Command` namespace provides an additional utility function to help you localize your extension. The `toLocalizedCommand` function accepts a *Command* and localization keys as its arguments. The first additional key will be used to localize the label and the second for the category. If none are provided, the *id* of the command will be used as the label localization key:
+
+```typescript
+command = Command.toLocalizedCommand({
+    id: 'hello-command',
+    label: 'Hello'
+    category: 'Greetings'
+}, 'hello', 'greetings');
+```
+
+After replacing the all user-facing strings with `nls.localize` calls, you can use the `theia nls-extract` command of the `@theia/cli` package to extract all used localization keys into a single JSON file. For the two examples above, it will result in the following JSON output:
+
+```json
+{
+    "bye": "Bye",
+    "hello": "Hello",
+    "greetings": "Greetings"
+}
+```
+
+You can also group these keys by using forward-slashes. For example, a call like `nls.localize('group/bye', 'Bye')` will be transformed into this JSON file:
+
+```json
+{
+    "group": {
+        "bye": "Bye"
+    }
+}
+```
+
+These files will have to be translated into your target languages. Afterwards, you can continue with registering these new localizations for your strings using a custom `LocalizationContribution`:
+
+```typescript
+// creating your own localization contribution for German, Italian and simplified Chinese
+export class CustomLocalizationContribution implements LocalizationContribution {
+    async registerLocalization(registry: LocalizationRegistry): Promise<void> {
+        // Theia uses language codes, e.g. "de" for German
+        registry.registerLocalizationFromRequire('de', require('../data/i18n/nls.de.json');
+        registry.registerLocalizationFromRequire('it', require('../data/i18n/nls.it.json');
+        registry.registerLocalizationFromRequire('zh-cn', require('../data/i18n/nls.zh-cn.json');
+    }
+}
+```
+
+Lastly, this `LocalizationContribution` will have to be bound within your frontend injection module:
+
+```typescript
+bind(CustomLocalizationContribution).toSelf().inSingletonScope();
+bind(LocalizationContribution).toService(CustomLocalizationContribution);
+```
+
+Be aware that the `Configure Display Language` command only shows a locale once its language pack has been installed. This assures that no parts of the Theia base framework remain untranslated after a user changes the display language.
diff --git a/src/docs/menu.js b/src/docs/menu.js
index 55aff920..e8532b2e 100644
--- a/src/docs/menu.js
+++ b/src/docs/menu.js
@@ -105,6 +105,10 @@ export const MENU = [
         'Tasks',
         'tasks'
     ),
+    M(
+        'Internationalization',
+        'i18n'
+    ),
     {
         title: 'Theia Blueprint'
     },