Symfony UX Translator

编辑此页

实验性功能 此组件目前为实验性功能，可能会发生变化，甚至可能发生重大变化。

Symfony UX Translator 是一个 Symfony 扩展包，它在 JavaScript 中提供了与 Symfony Translator 相同的机制，并集成了 TypeScript，用于 Symfony 应用程序。它是 Symfony UX 倡议的一部分。

也支持 ICU 消息格式。

安装

注意

此包与 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 翻译。不必担心您最终的 bundle 大小，由于 tree shaking，只有您使用的翻译才会包含在您最终的 bundle 中。

配置导出的翻译文件

默认情况下，您的所有翻译都将被导出。您可以通过在 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 框架相同的向后兼容性承诺：http://symfony.ac.cn/doc/current/contributing/code/bc.html

这项工作，包括代码示例，根据 Creative Commons BY-SA 3.0 许可协议获得许可。

版本