-
Notifications
You must be signed in to change notification settings - Fork 8
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
docs(tutorial): add localization steps (#471)
* docs(tutorial): add localization steps * fix: admonition
- Loading branch information
1 parent
53d273c
commit 89f90ea
Showing
8 changed files
with
439 additions
and
49 deletions.
There are no files selected for viewing
This file was deleted.
Oops, something went wrong.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,64 @@ | ||
--8<-- "References/abbreviations.md" | ||
|
||
React supports localization of applications into different languages through the use of i18n. This example below will walk through how to add support for the language, Kannada. These steps can be applied to a language that fits your desired requirements. | ||
|
||
## Localize the Strings | ||
|
||
1. Navigate to the `ui-toolkit-react/src/public/locales/` directory. | ||
|
||
2. Create a new `kn/` directory within the `ui-toolkit-react/src/public/locales/` directory. | ||
|
||
The directory name must match one of the [codes listed](https://developers.google.com/admin-sdk/directory/v1/languages). | ||
|
||
|
||
3. Copy the `translation.json` file in the `/locales/en/` directory to the new `/locales/kn/` language directory. | ||
|
||
4. Translate the strings in the copied `translation.json` file to the new language. | ||
|
||
5. Save and close the file. | ||
|
||
## Add to Bundle | ||
|
||
1. Open the `i18n.ts` file in the `ui-toolkit-react/src/public/` directory. | ||
|
||
2. Import the new `public/locales/kn/translation.json` file. | ||
|
||
``` ts hl_lines="6" | ||
import i18n from 'i18next' | ||
import LanguageDetector from 'i18next-browser-languagedetector' | ||
import { initReactI18next } from 'react-i18next' | ||
|
||
import translationEN from './public/locales/en/translation.json' | ||
import translationKN from './public/locales/kn/translation.json' | ||
... | ||
``` | ||
|
||
3. Edit the `resources` const to include the new translation. | ||
|
||
``` ts hl_lines="8-10" | ||
... | ||
import translationEN from './public/locales/en/translation.json' | ||
import translationKN from './public/locales/kn/translation.json'; | ||
|
||
const resources = { | ||
en: { | ||
translations: translationEN | ||
}, | ||
kn: { | ||
translations: translationKN | ||
} | ||
}; | ||
... | ||
``` | ||
|
||
4. Save the file. | ||
|
||
5. Rebuild and generate a new bundle before testing the changes. | ||
|
||
Language can be changed in the browser under language section of the browser settings. English is the default language if no customized translation file is provided for an alternative language. | ||
|
||
## Get Localized Strings for Web Consoles with Localization Enabled | ||
|
||
If your web console already has localization enabled, make sure to add the [translations](https://github.com/open-amt-cloud-toolkit/ui-toolkit-react/tree/main/src/public/locales) of the UI-controls into your web console's translations file. | ||
|
||
<br><br> |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,142 @@ | ||
--8<-- "References/abbreviations.md" | ||
|
||
# Console Localization | ||
|
||
Console is based on an implementation of the Sample Web UI. By modifying the Sample Web UI, we can build a translated Console application. | ||
|
||
The Sample Web UI is built on Angular which supports localization for additional languages using i18n. This tutorial will show how Console can be built in a new language, French. | ||
|
||
## What You'll Need | ||
|
||
**Software on the Development System** | ||
|
||
- [git*](https://git-scm.com/downloads) | ||
- [Node.js](https://nodejs.org/en/download/package-manager) | ||
- [Angular](https://angular.dev/installation) | ||
- [Go* Programming Language](https://go.dev/) | ||
|
||
## What You'll Do | ||
The following sections describe how to: | ||
|
||
- Create a Translation File | ||
- Update the Sample Web UI Configuration | ||
- Build Console Application | ||
|
||
These steps highlight how to build Console in a French translation. | ||
|
||
## Clone the Sample Web UI and Console | ||
|
||
1. If you do not have the Sample Web UI repository, clone the latest version. | ||
|
||
``` | ||
git clone https://github.com/open-amt-cloud-toolkit/sample-web-ui.git --branch v{{ repoVersion.webui }} | ||
``` | ||
|
||
2. If you do not have the Console repository, clone the latest version. | ||
|
||
``` | ||
git clone https://github.com/open-amt-cloud-toolkit/console.git | ||
``` | ||
|
||
## Translate Strings | ||
|
||
1. Open the `messages.xlf` file in `sample-web-ui/src/locale/`. | ||
|
||
This file contains all of the strings and their locations within the Sample UI. These need to be translated. | ||
|
||
2. Make a copy of the `messages.xlf` source language file. | ||
|
||
3. Rename the copy to `messages.fr.xlf` for our target French translation. | ||
|
||
4. Translate the file using a text editor or XLIFF editor tool. [See the Angular Translation Documentation for more information.](https://v17.angular.io/guide/i18n-common-translation-files#translate-each-translation-file) | ||
|
||
5. Save the file. | ||
|
||
## Update Sample Web UI Configuration | ||
|
||
Now that we have a translated `.xlf` file, we can modify the Sample Web UI configuration to utilize it when building the bundle. | ||
|
||
### Update `angular.json` | ||
|
||
1. Open the `angular.json` file in the `/sample-web-ui/` directory | ||
|
||
2. Add the below `i18n:` block to the `openamtui:` section. Additional locales can be appended for each additional language to support. | ||
|
||
```json hl_lines="14-22" | ||
... | ||
"openamtui": { | ||
"projectType": "application", | ||
"schematics": { | ||
"@schematics/angular:component": { | ||
"style": "scss" | ||
}, | ||
"@schematics/angular:application": { | ||
"strict": true | ||
} | ||
}, | ||
"root": "", | ||
"sourceRoot": "src", | ||
"i18n": { | ||
"sourceLocale": "en-US", | ||
"locales": { | ||
"fr": { | ||
"translation": "src/locale/messages.fr.xlf", | ||
"baseHref": "/" | ||
} | ||
} | ||
}, | ||
... | ||
``` | ||
|
||
3. Add `localize:` field to the `build:` section. | ||
|
||
```json hl_lines="9" | ||
... | ||
"build": { | ||
"builder": "@angular-devkit/build-angular:browser", | ||
"options": { | ||
"outputPath": "dist/openamtui", | ||
"index": "src/index.html", | ||
"main": "src/main.ts", | ||
"polyfills": "src/polyfills.ts", | ||
"localize": ["fr"], | ||
"tsConfig": "tsconfig.app.json", | ||
... | ||
``` | ||
|
||
4. Save the file. | ||
|
||
## Build Translated Console | ||
|
||
Now that the strings are translated and the deployment configurations are updated, we can build and run Console. | ||
|
||
1. Build the Sample Web UI. | ||
|
||
``` | ||
npm run build-enterprise | ||
``` | ||
|
||
2. Copy the newly generated `sample-web-ui/ui/` directory. | ||
|
||
3. Paste the directory into the `console/internal/app/controller/http/ui/` directory. | ||
|
||
4. Build the Console application. | ||
|
||
=== "Windows" | ||
``` bash | ||
go build -o console_windows_x64.exe ./cmd/app/main.go | ||
``` | ||
=== "Linux" | ||
``` bash | ||
go build -o console_linux_x64 ./cmd/app/main.go | ||
``` | ||
|
||
5. Run the executable. | ||
|
||
!!! example "Example - Console Home Page" | ||
<figure class="figure-image"> | ||
<img src="..\..\..\assets\images\Console_FrenchTranslation.png" alt="Figure 1: Console English Login Page"> | ||
<figcaption>Figure 1: Console English Login page</figcaption> | ||
</figure> | ||
|
||
<br><br> |
Oops, something went wrong.