Symfony UX Translator

編輯此頁

實驗性功能 這個元件目前為實驗性功能，可能會變更，甚至大幅變更。

Symfony UX Translator 是一個 Symfony 套件，在 JavaScript 中提供與 Symfony Translator 相同的機制，並整合 TypeScript，適用於 Symfony 應用程式。它是 Symfony UX 計畫的一部分。

同時也支援 ICU Message Format。

安裝

注意

這個套件最適合搭配 WebpackEncore 使用。若要搭配 AssetMapper 使用，請參閱搭配 AssetMapper 使用。

注意

在開始之前，請確認您的應用程式中已設定 StimulusBundle。

使用 Composer 和 Symfony Flex 安裝套件

        1
        $ composer require symfony/ux-translator
    

如果您使用 WebpackEncore，請安裝您的 assets 並重新啟動 Encore (如果您使用 AssetMapper 則不需要)

        1
2
        $ npm install --force
$ npm run watch
    

安裝套件後，應會建立下列檔案，這要歸功於 Symfony Flex recipe

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
        // assets/translator.js

/*
 * This file is part of the Symfony UX Translator package.
 *
 * If folder "../var/translations" does not exist, or some translations are missing,
 * you must warmup your Symfony cache to refresh JavaScript translations.
 *
 * If you use TypeScript, you can rename this file to "translator.ts" to take advantage of types checking.
 */

import { trans, getLocale, setLocale, setLocaleFallbacks } from '@symfony/ux-translator';
import { localeFallbacks } from '../var/translations/configuration';

setLocaleFallbacks(localeFallbacks);

export { trans }
export * from '../var/translations';
    

用法

在預熱 Symfony 快取時，您的翻譯將會以 JavaScript 形式傾印到 var/translations/ 目錄中。為了獲得更好的開發人員體驗，TypeScript 類型定義也會在這些 JavaScript 檔案旁邊產生。

然後，您將能夠在您的 assets 中匯入這些 JavaScript 翻譯。不用擔心最終的套件大小，只有您使用的翻譯會包含在最終的套件中，這要歸功於 tree shaking。

設定傾印的翻譯

預設情況下，您的所有翻譯都會匯出。您可以透過在您的 config/packages/ux_translator.yaml 檔案中包含或排除翻譯網域來限制傾印的訊息

        1
2
3
4
5
6
7
8
        ux_translator:
        domains: ~    # Include all the domains

        domains: foo  # Include only domain 'foo'
        domains: '!foo' # Include all domains, except 'foo'

        domains: [foo, bar]   # Include only domains 'foo' and 'bar'
        domains: ['!foo', '!bar'] # Include all domains, except 'foo' and 'bar'
    

設定預設語系

預設情況下，預設語系是 en (英文)，您可以透過多種方式設定 (依優先順序排列)

使用 @symfony/ux-translator 套件中的 setLocale('de') 或 setLocale('de_AT')
或使用 <html data-symfony-ux-translator-locale="{{ app.request.locale }}"> 屬性 (例如，使用 Symfony 語系格式的 de_AT 或 de)
或使用 <html lang="{{ app.request.locale|replace({ '_': '-' }) }}"> 屬性 (例如，遵循 W3C 語言代碼規範的 de-AT 或 de)

偵測遺失的翻譯

預設情況下，如果翻譯遺失，翻譯器將會傳回翻譯鍵。

您可以呼叫 throwWhenNotFound(true) 來變更此行為

        1
2
3
4
5
6
7
8
9
10
11
        // assets/translator.js

- import { trans, getLocale, setLocale, setLocaleFallbacks } from '@symfony/ux-translator';
+ import { trans, getLocale, setLocale, setLocaleFallbacks, throwWhenNotFound } from '@symfony/ux-translator';
  import { localeFallbacks } from '../var/translations/configuration';

  setLocaleFallbacks(localeFallbacks);
+ throwWhenNotFound(true)

  export { trans }
  export * from '../var/translations';
    

匯入和使用翻譯

如果您使用 Symfony Flex recipe，您可以從檔案 assets/translator.js 中匯入 trans() 函數和您的翻譯到您的 assets 中。

翻譯以具名匯出形式提供，透過使用以大寫蛇形式轉換的翻譯 ID (例如：my.translation 變成 MY_TRANSLATION)，因此您可以像這樣匯入它們

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
        // assets/my_file.js

import {
    trans,
    TRANSLATION_SIMPLE,
    TRANSLATION_WITH_PARAMETERS,
    TRANSLATION_MULTI_DOMAINS,
    TRANSLATION_MULTI_LOCALES,
} from './translator';

// No parameters, uses the default domain ("messages") and the default locale
trans(TRANSLATION_SIMPLE);

// Two parameters "count" and "foo", uses the default domain ("messages") and the default locale
trans(TRANSLATION_WITH_PARAMETERS, { count: 123, foo: 'bar' });

// No parameters, uses the default domain ("messages") and the default locale
trans(TRANSLATION_MULTI_DOMAINS);
// Same as above, but uses the "domain2" domain
trans(TRANSLATION_MULTI_DOMAINS, {}, 'domain2');
// Same as above, but uses the "domain3" domain
trans(TRANSLATION_MULTI_DOMAINS, {}, 'domain3');

// No parameters, uses the default domain ("messages") and the default locale
trans(TRANSLATION_MULTI_LOCALES);
// Same as above, but uses the "fr" locale
trans(TRANSLATION_MULTI_LOCALES, {}, 'messages', 'fr');
// Same as above, but uses the "it" locale
trans(TRANSLATION_MULTI_LOCALES, {}, 'messages', 'it');
    

搭配 AssetMapper 使用

將此程式庫與 AssetMapper 一起使用是可行的，但目前仍為實驗性功能，可能尚未準備好用於生產環境。

使用 AssetMapper 安裝時，Flex 將會新增一些新項目到您的 importmap.php 檔案中。其中 2 個新項目是

        1
2
3
4
5
6
        '@app/translations' => [
    'path' => 'var/translations/index.js',
],
'@app/translations/configuration' => [
    'path' => 'var/translations/configuration.js',
],
    

然後這些項目會匯入到您的 assets/translator.js 檔案中。此設定與使用 WebpackEncore 非常相似。但是，var/translations/index.js 檔案包含您應用程式中的所有翻譯，這對於生產環境來說並不理想，甚至可能會洩漏僅供管理區域使用的翻譯。Encore 透過 tree-shaking 來解決此問題，但 AssetMapper 元件則沒有。目前尚無使用 AssetMapper 元件正確解決此問題的方法。

向後相容性承諾

此套件旨在遵循與 Symfony 框架相同的向後相容性承諾：https://symfony.dev.org.tw/doc/current/contributing/code/bc.html

這項作品，包括程式碼範例，已根據 Creative Commons BY-SA 3.0 授權條款授權。

版本