Flutter自动翻译插件auto_translator的使用

Auto Translator

Auto Translator 是一个简化 ARB 模板文件翻译为选定语言的命令行工具。该包旨在与 flutter_localizations 和 intl 包无缝协作，这是 Flutter 的首选国际化方法。

功能特性

• 与 flutter_localizations 和 intl 包无缝集成。
• 支持 Google Cloud Translate 和 DeepL Translate。
• 最小化配额使用。
• 支持简单和复杂的 ARB 字符串、条件和变量。
• 使用占位符示例进行更准确的翻译，涉及专有名词和其他特殊案例。
• 可以为每个目标语言指定翻译服务和/或源语言。

开始使用

1. 设置翻译服务

Auto Translator 默认支持 Google Cloud Translate 和 DeepL。您可以在 l10n.yaml 配置文件中指定其中一个作为主要服务。如果未提供，则默认使用 Google 翻译。您也可以在每个语言的基础上指定不同的翻译器，如首选服务部分所述。

如果您只配置一个服务，可以将 API 密钥保存在项目根目录下的 translator_key 文件中，或者以 JSON 映射的形式保存在 translator_keys 中。如果配置两个服务，则必须使用 JSON 映射方法。

⚠️ 请勿 将您的密钥文件发布到 GitHub 或类似的版本控制系统中。

Google Cloud Translate

如果您还没有启用了 Cloud Translation API 的 Google Cloud 项目，请按照这里的指南操作。

DeepL Translate

如果您没有 DeepL API 访问权限，请按照 DeepL 的指南创建账户并获取 API 访问权限，详情请参阅这里。

2. 添加 auto_translator 到您的项目

在 pubspec.yaml 文件中的 dev_dependencies 下添加 auto_translator：

dev_dependencies:
  auto_translator: ^2.3.2

3. 设置配置文件

auto_translator 使用与 intl 包相同的配置文件，这是 Flutter 推荐的应用程序国际化的包，具体说明请参见这里。

如果您还没有创建 l10n.yaml 文件，请现在创建它。

arb-dir: lib/l10n
template-arb-file: app_en.arb
output-localization-file: app_localizations.dart

translator:
  # 默认为 Google Translate
  service: Google

  targets:
    - es-ES
    - fr
    - ja

前三个参数由 intl 和 auto_translator 共同使用。translator 部分是特定于 auto_translator 的。

targets 参数是必需的，它告诉 auto_translator 要将模板文件翻译成哪些语言。可用语言列表请参见这里。

您还可以为任何给定的目标语言配置首选源模板。

区域指定

您可以使用两位字母的语言代码和区域指定（如 en-US、en-GB、es-Es 等）。

4. 运行包

配置完成后，从命令行运行包：

flutter pub get
dart run auto_translator

所有翻译都将放置在定义的位置，并且与 flutter_localizations 和 intl 兼容。

额外用法

占位符示例

某些翻译在使用示例代替通用占位符变量名称时更准确。auto_translator 现在会传递占位符的示例以确保更好的翻译质量。

"viewingArtwork": "Now viewing {artworkTitle}.",
"@viewingArtwork": {
    "placeholders": {
        "artworkTitle": {
            "type": "String",
            "example": "Mona Lisa"
        }
    }
}

强制翻译

为了防止不必要的 Google Cloud Translate 配额使用，已经存在于目标 ARB 文件中的消息不会被重新翻译。您可以通过在模板文件中消息的元数据中添加 force 参数来强制翻译。

"title": "New Title",
"@title": {
  "description": "...",
  "translator": {
    "force": true
  }
}

忽略 ARB 字符串

您也可以通过 ignore 标签告诉翻译器忽略特定的消息。

"doNotTranslate": "DO NOT TRANSLATE THIS STRING!!!",
"@doNotTranslate": {
  "description": "...",
  "translator": {
    "ignore": true
  }
}

首选模板

有时，您可能希望为某个目标语言指定一个比 template-arb-file 中使用的语言更准确的源语言模板。为此，您可以在配置文件中提供 prefer-lang-templates 映射，以指定任何目标语言的首选源语言。

translator:
  # 使用 es-ES 模板进行 fr 翻译，ja 模板进行 ko 翻译
  # 所有其他翻译将使用 [template-arb-file]
  prefer-lang-templates:
    fr: es
    ko: ja

首选服务

由于一个服务在某种语言上可能优于另一个服务，您可以在配置文件中提供 prefer-service 映射，以按语言指定服务。

translator:
  # 使用 DeepL 进行 tr 和 uk 翻译
  # 所有其他翻译将使用主要服务（假设是 Google）
  prefer-service:
    # 服务名称的大小写不敏感
    DeepL:
      - tr
      - uk

每个 API 密钥必须在密钥文件中提供（服务名称的大小写不敏感）。

{
  "google": "CLOUD_TRANSLATE_API_KEY",
  "deepL": "DEEP_L_API_KEY"
}

替代配置文件

默认情况下，配置文件名为 l10n.yaml 并位于项目的根目录中。您可以通过在命令行运行时使用 --config-file 选项传递替代文件路径。

替代密钥文件

默认情况下，auto_translator 在项目根目录下查找 translator_keys 或 translator_key。您可以在配置文件中指定不同的位置。

translator:
  key_file: path/to/key/file

示例代码

以下是一个完整的示例代码，展示了如何在 Flutter 应用中使用 auto_translator 生成的本地化资源。

import 'package:flutter/material.dart';
import 'package:flutter_gen/gen_l10n/app_localizations.dart';

void main() {
  runApp(const MyApp());
}

class MyApp extends StatefulWidget {
  const MyApp({Key? key}) : super(key: key);

  @override
  State<MyApp> createState() => _MyAppState();
}

class _MyAppState extends State<MyApp> {
  var locale = const Locale('en');
  var _counter = 0;

  void _incrementCounter() {
    setState(() {
      _counter++;
    });
  }

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      debugShowCheckedModeBanner: false,
      localizationsDelegates: AppLocalizations.localizationsDelegates,
      onGenerateTitle: (context) => AppLocalizations.of(context)!.appTitle,
      theme: ThemeData(
        primarySwatch: Colors.blue,
      ),
      supportedLocales: AppLocalizations.supportedLocales,
      locale: locale,
      home: Builder(builder: (context) {
        final localizedText = AppLocalizations.of(context)!;
        return Scaffold(
          appBar: AppBar(
            title: FittedBox(child: Text(localizedText.homePageTitle)),
            actions: [
              PopupMenuButton<Locale>(
                itemBuilder: (context) => AppLocalizations.supportedLocales
                    .map(
                      (locale) => PopupMenuItem(
                        value: locale,
                        child: Text(locale.languageCode),
                      ),
                    )
                    .toList(),
                onSelected: (locale) => setState(() => this.locale = locale),
              )
            ],
          ),
          body: Center(
            child: Text(
              localizedText.buttonPresses(_counter),
              style: const TextStyle(fontSize: 28.0),
              textAlign: TextAlign.center,
              softWrap: true,
            ),
          ),
          floatingActionButton: FloatingActionButton(
            onPressed: _incrementCounter,
            tooltip: localizedText.tooltip,
            child: const Icon(Icons.add),
          ),
        );
      }),
    );
  }
}

这个示例展示了如何使用 auto_translator 生成的本地化资源来实现多语言支持的应用程序。通过选择不同的语言，应用程序的文本会根据所选语言进行相应的翻译。