diff --git a/docs/Reference/UIToolkit/localization.md b/docs/Reference/UIToolkit/localization.md deleted file mode 100644 index 35380ec60..000000000 --- a/docs/Reference/UIToolkit/localization.md +++ /dev/null @@ -1,46 +0,0 @@ -## Localize Strings - -1. Create a new directory in the `ui-toolkit/public/locales/` directory. The directory name must match one of the [codes listed](https://developers.google.com/admin-sdk/directory/v1/languages). - -2. Copy the *translation.json* file in the `public/locales/en/` directory to the new language directory. - -3. Customize the required fields in the translation.json file. - - !!! example - To support Kannada language: - - 1. Create a new directory `kn` in `/public/locales/` - 2. Copy *translation.json* from `/locales/en/` to `/locales/kn/` directory - 3. Update key-values in */kn/translation.json* according to Kannada language - - -4. Open the *i18n.ts* file in the `ui-toolkit` directory. - -5. Modify the file to import the newly added *public/locales/Language/translation.json* file and update the 'resources' constant to include the new translation. - - !!! example - To support Kannada language: - - 1. Create new import statement as 'translationKN' - 2. Edit resources constant to include new translation - - ``` - import translationEN from './public/locales/en/translation.json' - import translationKN from './public/locales/kn/translation.json'; - const resources = { - en: { - translations: translationEN - }, - kn: { - translations: translationKN - } - }; - ``` - - 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 if no customized translation file provided for the 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. diff --git a/docs/Reference/UIToolkit/reactLocalization.md b/docs/Reference/UIToolkit/reactLocalization.md new file mode 100644 index 000000000..9be1c4084 --- /dev/null +++ b/docs/Reference/UIToolkit/reactLocalization.md @@ -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. + +

\ No newline at end of file diff --git a/docs/Tutorials/Localization/consoleLocalization.md b/docs/Tutorials/Localization/consoleLocalization.md new file mode 100644 index 000000000..d17142928 --- /dev/null +++ b/docs/Tutorials/Localization/consoleLocalization.md @@ -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 1: Console English Login Page +
Figure 1: Console English Login page
+
+ +

\ No newline at end of file diff --git a/docs/Tutorials/Localization/webuiLocalization.md b/docs/Tutorials/Localization/webuiLocalization.md new file mode 100644 index 000000000..d3da781e8 --- /dev/null +++ b/docs/Tutorials/Localization/webuiLocalization.md @@ -0,0 +1,226 @@ +--8<-- "References/abbreviations.md" + +# Sample Web UI Localization + +The Sample Web UI is based on Angular. Angular supports localization for additional languages using i18n. This tutorial will show how support for a new language, French, can be added to the Sample Web UI. + +## What You'll Need + +**Software on the Development System** + +- [git*](https://git-scm.com/downloads) +- [Docker* for Windows*](https://docs.docker.com/desktop/install/windows-install/) or [Docker* for Linux*](https://docs.docker.com/desktop/install/linux-install/) + +## What You'll Do +The following sections describe how to: + +- Create a Translation File +- Update the Sample Web UI Configuration +- Deploy the translated Sample Web UI using Docker + +These steps highlight how to serve the Sample Web UI in both English and a newly added language, French. + +## Clone the Sample Web UI + +1. If you do not have the repository, clone the latest Sample Web UI. + + ``` + git clone https://github.com/open-amt-cloud-toolkit/sample-web-ui.git --branch v{{ repoVersion.webui }} + ``` + +## 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 and image. + +### 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": "/fr/" + } + } + }, + ... + ``` + +3. Add `localize:` field to the `build:` section. + + !!! note "Note - Using `localize:` on Angular Development Server" + `localize: true` will build application variants for all locales defined in the build configuration. This is ideal for production. If you want to build and serve on the Angular development server for testing, this will cause errors. Angular development server can only support localizing a single locale at a time. + + To build only one locale, see [Apply specific build options for just one locale](https://angular.dev/guide/i18n/merge#apply-specific-build-options-for-just-one-locale) Angular Documentation. + + ```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": true, + "tsConfig": "tsconfig.app.json", + ... + ``` + +4. Save the file. + +### Update `init.sh` + +1. Open the `init.sh` file in the `/sample-web-ui/` directory. + +2. Modify the last line of the file to the following. + + ```sh hl_lines="6" + sed -i \ + -e "s|##RPS_SERVER##|$RPS_SERVER|g" \ + -e "s|##MPS_SERVER##|$MPS_SERVER|g" \ + -e "s|##VAULT_SERVER##|$VAULT_SERVER|g" \ + -e "s|##AUTH_MODE_ENABLED##|$AUTH_MODE_ENABLED|g" \ + /usr/share/nginx/html/*/*.js + ``` + +3. Save the file. + +### Update `nginx.conf` + +1. Open the `nginx.conf` file in the `/sample-web-ui/` directory. + +2. Copy and paste the new configuration below. + + ```conf + server { + listen 80 default_server; + listen [::]:80 default_server; + server_name _; + + root /usr/share/nginx/html; + index index.html index.htm; + + # Set default language to en-US + if ($accept_language ~ "^$") { + set $accept_language "en-US"; + } + + # Redirect "/" to Angular application in the preferred language of the browser + rewrite ^/$ /$accept_language; + + # Everything under the Angular application is always redirected to Angular in the correct language + location ~ ^/(fr|en-US) { + try_files $uri /$1/index.html?$args; + } + + error_page 404 /index.html; + + # redirect server error pages to the static page /50x.html + # + error_page 500 502 503 504 /50x.html; + location = /50x.html { + root /usr/share/nginx/html; + } + } + ``` + +3. Save the file. + +### Update `Dockerfile` + +1. Open the `Dockerfile` file in the `/sample-web-ui/` directory. + +2. Update the following lines in Stage 2. + + ```dockerfile hl_lines="9-10" + ### STAGE 2: Run ### + FROM nginx:mainline-alpine-slim@sha256:a529900d9252ce5d04531a4a594f93736dbbe3ec155a692d10484be82aaa159a + + LABEL license='SPDX-License-Identifier: Apache-2.0' \ + copyright='Copyright (c) 2021: Intel' + + RUN apk update && apk upgrade --no-cache + + COPY --from=build /usr/src/app/dist/openamtui/en-US /usr/share/nginx/html/en-US + COPY --from=build /usr/src/app/dist/openamtui/fr /usr/share/nginx/html/fr + COPY --from=build /usr/src/app/init.sh /docker-entrypoint.d/init.sh + EXPOSE 80 + ``` + +3. Save the file. + +## Deploy Translated Sample Web UI + +Now that the strings are translated and the deployment configurations are updated, we can build and start the Sample Web UI. + +1. Build the image and start the container. + + ``` + docker compose up -d + ``` + +2. Navigate to the Sample Web UI in a browser. + + ``` + http://localhost:8089 + ``` + + With no path provided, it should default to `/en-US/` and display the English page. + + !!! example "Example - Sample Web UI Home Page" +
+ Figure 1: Sample Web UI English Login Page +
Figure 1: Sample Web UI English Login page
+
+ +3. Change the URL path to `/fr`. + + ``` + http://localhost:8089/fr + ``` + + The page should now be displaying the French translated site. + + !!! note "Note - File Structure" + Adding languages adds an additional nesting to the file structure. It is important to verify all images and other assets are still working. Some assets may need minor tweaks to file paths to ensure they work correctly. + + !!! example "Example - Sample Web UI Home Page" +
+ Figure 2: Sample Web UI French Login Page +
Figure 2: Sample Web UI French Login page
+
+ +

\ No newline at end of file diff --git a/docs/assets/images/Console_FrenchTranslation.png b/docs/assets/images/Console_FrenchTranslation.png new file mode 100644 index 000000000..22dd5c680 Binary files /dev/null and b/docs/assets/images/Console_FrenchTranslation.png differ diff --git a/docs/assets/images/SampleUI_EnglishTranslation.png b/docs/assets/images/SampleUI_EnglishTranslation.png new file mode 100644 index 000000000..11415577f Binary files /dev/null and b/docs/assets/images/SampleUI_EnglishTranslation.png differ diff --git a/docs/assets/images/SampleUI_FrenchTranslation.png b/docs/assets/images/SampleUI_FrenchTranslation.png new file mode 100644 index 000000000..794449f45 Binary files /dev/null and b/docs/assets/images/SampleUI_FrenchTranslation.png differ diff --git a/mkdocs.yml b/mkdocs.yml index 5eedc4492..04dc2981f 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -88,6 +88,9 @@ nav: - IDE-Redirection (IDER): Tutorials/ideRedirection.md - Wireless Activation: Tutorials/createWiFiConfig.md - Modify User Authentication: Tutorials/modifyUserAuth.md + - Localization: + - Console: Tutorials/Localization/consoleLocalization.md + - Sample Web UI: Tutorials/Localization/webuiLocalization.md - Scaling Tutorials: - Overview: Tutorials/Scaling/overview.md - Docker Swarm*: Tutorials/Scaling/docker-swarm.md @@ -140,11 +143,11 @@ nav: - RPC CLI: Reference/RPC/commandsRPC.md - RPC Library: Reference/RPC/libraryRPC.md - Transition Activated Device: Reference/RPC/transitionDeviceRPC.md - - UI Toolkit: - - Controls: + - UI Toolkit React: + - React Controls: - Keyboard, Video, Mouse: Reference/UIToolkit/Controls/kvmControl.md - Serial Over LAN: Reference/UIToolkit/Controls/serialOverLANControl.md - - Localization: Reference/UIToolkit/localization.md + - React Localization: Reference/UIToolkit/reactLocalization.md - React Bundles: - Keyboard, Video, Mouse: Reference/UIToolkit/Bundles/kvmReact.md - Serial Over LAN: Reference/UIToolkit/Bundles/serialOverLANReact.md @@ -219,6 +222,7 @@ extra: rpsAPI: 2.22.0 oamtct: 2.25.0 rpc_go: 2.37.0 + webui: 3.15.0 rpc_c: 2.0.0 ui_toolkit: 3.2.8 ui_toolkit_react: 3.2.8