Month: May 2020

Angular i18n 的官方作法並不讓人滿意，我後來找到 ngx-translate

先說明一下他的作法，他把這些翻譯好的字詞放到 JSON 翻譯檔去，在執行時就可以透過 http client 去拉取回來作動態的替換。

好處是，程式只要建置一次，不需要針對個別語言再次建置，網頁伺服器那邊也不需要特別寫設定去處理，而且可以做到動態切換語言。壞處是會有額外的 HTTP 請求，會增加流量。

ngx-translate 額外好的地方是，他提供了相應的工具、plugin，相當的方便。

那麼怎麼使用呢？我推薦看這篇【Angular】ngx-translate 多語系實務應用 ，他這篇的缺點是萃取字串的部分是手動，我建議萃取字串的部分可以用原作者 biesbjerg 的 ngx-translate-extract  ，就不用自己找字串找的太累。

先進行安裝

npm install @ngx-translate/core —save
npm install @ngx-translate/http-loader --save

然後改 app.module.ts

import { TranslateModule, TranslateLoader, TranslateCompiler } from '@ngx-translate/core';
import { TranslateHttpLoader } from '@ngx-translate/http-loader';
import { TranslateMessageFormatCompiler } from 'ngx-translate-messageformat-compiler';
import { HttpClientModule, HttpClient } from '@angular/common/http';

// … 省略 …

// 這主要是告訴 ngx-translate 翻譯檔該怎麼載入，用 TranslateHttpLoader 是表示以 HTTP 方式去下載、載入
export function HttpLoaderFactory(http: HttpClient) {
  return new TranslateHttpLoader(http, './assets/i18n/', '.json');
}

// … 省略 …

// 設定
const translateConfig = {
  defaultLanguage: 'en-US',  // 預設是英文
  loader: {
    provide: TranslateLoader,
    useFactory: HttpLoaderFactory,  // 前面寫的 Factory
    deps: [HttpClient]
  },
  compiler: {
    provide: TranslateCompiler,
    useClass: TranslateMessageFormatCompiler
  }
};

@NgModule({
  // …
  imports: [
    BrowserAnimationsModule,
    BrowserModule,
    TranslateModule.forRoot(translateConfig),  // 模組帶設定
    // …
  ],
  // …
})

在 HTML 裡，使用

// 方法 1
{{ ‘your_translation_key’ | translate }}

// 方法 2
<div [translate]=“‘your_translation_key’”></div>

// 方法 3，適用於字串要用 HTML
<div [innerHTML]="'HELLO' | translate"></div>

他還可以帶參數，只是這邊我看不太懂，暫時也還用不到。

在程式裡，使用

// 先匯入
import {TranslateService} from '@ngx-translate/core';
import { marker as _ } from '@biesbjerg/ngx-translate-extract-marker';

// … 省略 …
export class AppComponent implements OnInit {
  l10n__title = '';

  constructor(public translate: TranslateService) {
  }

  ngOnInit(): void {
    const self = this;

    // 讓 ngx-translate-extract 可以抓到字串用的
    _('your_translation_key');

    // 取得字串都要使用 translate.get() 來預先取得
    this.translate.get('your_translation_key').subscribe((res: string) => {
      self.l10n__title = res;
    });
  }
}

這裡要特別說明一點，也是我當初用的時候搞錯的地方，就是上面用到的 your_translation_key 並不是字串，而是你自定義的代碼，裡面有使用 ‘.’ 的時候，在產出的 JSON 裡會變成 nested object ，舉個例子，假設這個 key 是 login.title，那麼 JSON 翻譯檔就會是

{
  "login": {
    "title": ""
  }
}

接下來講 ngx-translate-extract，ngx-translate-extract 的安裝

npm install @biesbjerg/ngx-translate-extract --save-dev

裝好以後，在 package.json 的 scripts 裡加入 (要產生什麼語言，請替換 {en,da,de,fi,nb,nl,sv} 這個字串，以繁體中文來說，是zh-TW或zh-Hant，只有英文跟繁體中文的話，就放 {en-US,zh-TW}。 )

// package.json
...
"scripts": {
  "i18n:init": "ngx-translate-extract --input ./src --output ./src/assets/i18n/template.json --key-as-default-value --replace --format json",
  "i18n:extract": "ngx-translate-extract --input ./src --output ./src/assets/i18n/{en,da,de,fi,nb,nl,sv}.json --clean --format json"
}
...

然後建立存放字串的資料夾：mkdir -p src/assets/i18n，執行 npm run i18n:extract 以後，就可以在 src/assets/i18n 裡看到翻譯檔了。

以我用過 Django / Docker 的經驗，一般都是利用環境變數來作分離，程式在執行時，會去讀取環境變數來當作設定，盡量不依靠設定檔，進而達到 12 factor –  config 的要求。

到了 Angular ，就需要做出調整。Angular 是需要先進行建置產出 javascript / html / css ，再把這些產出的檔案放到網頁伺服器，瀏覽器再去下載，所以完全沒辦法使用環境變數作為設定，必須要把設定寫到檔案裡，再做建置。那設定寫到檔案的話，其實我們都知道，這些敏感設定內容不適合放到 git repository，即使是 private repository，這樣會有安全上的風險。那這樣就兩難了啊？

說來很妙，我是覺得官方早就應該有比較好的作法了，但是，並沒有。不管怎麼樣，我還是找到解決方法了，基本上跟我想的也差不多。

• GitHub Actions: Hide And Set Angular Environment Variables
• How to pass environment variables at building time in an Angular application using .env files

這兩篇文章的作法大同小異，這邊作簡單的說明：

1. 移除 src/environment/environment.ts
2. 新增一個腳本，這個腳本會讀取環境變數，並產生一個新的 src/environment/environment.ts
3. 修改 package.json
   1. 在 scripts 裡增加 config，這個 config 會去執行步驟 2 的腳本，用以產生 environment.ts
   2. 修改 scripts 裡的 start / build，在執行原來的指令前，先執行 npm run config 去產生 environment.ts

下面兩個片段是關鍵的改動部分：

// set-env.ts
// 放在專案根目錄下
import { writeFile } from 'fs';
import { name, version } from './package.json';


// Configure Angular `environment.ts` file path
const targetPath = './src/environments/environment.ts';


// 載入 colors 模組，主要是用來顯示
const colors = require('colors');


// 可以把敏感內容放到 .env 檔案裡，nodejs 會把內容讀出來，放到環境變數裡
// 也可以在執行 npm run 之前，先設定好環境變數
const result = require('dotenv').config();
if (result.error) {
  // throw result.error;
}


// 原來 environment.ts 裡的內容，把該替換的，用 template literals 來替換

// https://developer.mozilla.org/zh-TW/docs/Web/JavaScript/Reference/Template_literals
const envConfigFile = `export const environment = {
  production: ${process.env.PRODUCTION},
  VERSION: '${version}’,
};

`;


// 顯示
console.log(colors.magenta('The file `environment.ts` will be written with the following content: \n'));
console.log(colors.grey(envConfigFile)); writeFile(targetPath, envConfigFile, (err) => {
  if (err) {
    throw console.error(err);
  } else {
    console.log(colors.magenta(`Angular environment.ts file generated correctly at ${targetPath} \n`));
  }
});

// package.json
// 只摘錄重要的部分
{
  “scripts”: {
    "config": "ts-node -O '{\"module\": \"commonjs\"}' ./set-env.ts",
    "start": "npm run config && ng serve",
    "build": "npm run config && ng build”
  }
}

Angular 官方提供的套件以及教學：Angular Internalization (i18n)

文章裡一大堆，簡單整理如下：

1. 安裝：ng add @angular/localize
   • 這個步驟會幫你在 polyfills.ts 裡加入必要的 import
2. 使用，這部份分為 HTML 跟程式
   • HTML，在需要多國語言的標籤加入 i18n 的屬性
     • <span i18n>Hello world</span>
     • <span i18n=“@@span_hello”>Hello world</span> ，用 i18n=“@@span_hello” 的好處是，產出的翻譯檔裡不會是一個隨意的數字，而是一個對開發者來說比較明確的名稱。
     • <input i18n-placeholder> 這個是有些屬性本身需要多國語言的，就在前面加上 “i18n-“
   • 程式，字串前方加上 $localize ，並且改用 back quote，例如：$localize`hello world`
3. 萃取，用 ng xi18n –output-path src/i18n 就可以把 HTML 裡有標 i18n 的字串萃取到 src/i18n/messages.xlf 裡
4. 翻譯，先把上個步驟取得的 messages.xlf 複製為 messages.zh_Hant.xlf ，再去編輯。這邊提供一個簡易的網頁工具 – tiny-translator，在處理上會方便很多。開啟以後，要先建立專案，然後上傳 .xlf 檔案，接著就可以進行翻譯了。翻譯好，再下載下來即可。
5. 合併，程式開發中難免會有增刪，每次用 xi18n 基本上都是重新萃取一次，等於是又要再搞一次合併的功夫，這太累。tiny-translator 的作者有提供另外一個工具 – xliffmerge 
   • 安裝：npm install -g ngx-i18nsupport
   • 在 package.json 的 scripts 裡加入 “extract-i18n”: “ng xi18n –output-path src/i18n && xliffmerge –profile xliffmerge.json en de” ，裡面的 en, de 等 locale 請依照自己的需求作調整
   • 新增 xliffmerge.json ，這個檔案請參考後面。
   • 使用 npm run extract-i18n 就可以自動萃取字串並且作合併了。
6. 專案的建置，主要是修改 angular.json，有三個部分：
   • projects / your_project_name 加入 “i18n”: {“sourceLocale”: “en”, “locales”: {“de”: “src/i18n/messages.de.xlf”}}
   • projects / your_project_name / architect / build / configurations 裡加入 “de”: {“localize”: [“de”]}
   • projects / your_project_name / architect / serve / configurations 裡加入 “de”: {“browserTarget”: “ng-hosting:build:de”}
7. 要執行 ng build / ng serve 時，就可以用
   • ng build –configuration=production,de
   • ng serve –configuration=de
8. 補充一個我覺得很重要的部分，就是一個語言要建置一次，所以一般的佈署會是這樣的，建置好 zh ，放在 zh/ 目錄下，建置好 de，放在 de/ 目錄下，然後在 nginx/apache 的設定裡去依照 header 的 language 去導向到對應的目錄去。這篇 Deploying an i18n Angular app with angular-cli 的後面有教怎麼去設定 apache / nginx。

看到這邊，你可能會想，那程式裡標上 $localize 的字串呢？嗯，ng xi18n 並不會把這些字串萃取出來 (issue)，所以這部份得自己手動處理 😣 

P.S. 用 ngx-i18nsupport 的 tooling 可以把上面講的簡化掉，像是加入 npm package、在 package.json 加入 extract-i18n 、在 angular.json 加入設定等等，一次就搞定了，我是已經用了才看到這個 tooling ，有點相見恨晚。

// xliffmerge.json
{
  "xliffmergeOptions": {
    "srcDir": "src/i18n",
    "genDir": "src/i18n",
    "i18nFile": "messages.xlf",
    "i18nBaseFile": "messages",
    "i18nFormat": "xlf",
    "encoding": "UTF-8",
    "defaultLanguage": "en",
    "languages": ["en", "de"],
    "removeUnusedIds": true,
    "supportNgxTranslate": false,
    "ngxTranslateExtractionPattern": "@@|ngx-translate",
    "useSourceAsTarget": true,
    "targetPraefix": "",
    "targetSuffix": "",
    "beautifyOutput": false,
    "preserveOrder": true,
    "allowIdChange": false,
    "autotranslate": false,
    "apikey": "",
    "apikeyfile": "",
    "verbose": false,
    "quiet": false
  }
}