フォーマット
アプリケーションに必要な構造を保ちながらテキストを翻訳できるファイルハンドラーを見つけましょう。
ロケールファイルに含まれるのは、言葉だけではありません。キーはメッセージとコードを結び付け、プレースホルダーはアプリケーションの値を受け取り、ファイル構造は翻訳結果の読み込み方をフレームワークに伝えます。ドキュメントには、さらに見出し、リンク、例、メタデータが加わります。ファイルの翻訳では、こうしたつながりを保ったまま言語を変える必要があります。
Lingo.devはフォーマットハンドラーを使って翻訳対象のテキストを選び、翻訳結果を再構成します。ハンドラーは、ファイルが何を表すかに応じて選んでください。RailsのカタログとOpenAPI仕様は、どちらも拡張子が.ymlの場合がありますが、すべての文字列を翻訳すると、それぞれ異なる問題が生じます。Railsではロケールのルートを変更する必要がある一方、APIの操作識別子は変更せずに維持する必要があります。
フォーマットを探す #
| ソース | ハンドラーの種類 | リファレンス |
|---|---|---|
| 入れ子構造のJSONカタログ | json | JSON |
| コンテキストコメント付きJSON | jsonc | JSONC |
| YAMLカタログ | yaml | YAML |
| 単一のロケールルートを持つYAML | yaml-root-key | ロケールルート付きYAML |
| 静的なTypeScriptロケールモジュール | typescript | TypeScript |
| 静的なPHPロケール配列 | php | PHP |
| Markdownドキュメント | md | Markdown |
| JSXコンポーネントを含むMarkdown | mdx | MDX |
| Markdocドキュメント | markdoc | Markdoc |
| OpenAPI 3.xのYAML | yaml-openapi | OpenAPI |
| AndroidリソースXML | android | Android |
| Flutterアプリケーションリソースバンドル | flutter | Flutter ARB |
| Appleの文字列テーブル | xcode-strings | Appleのstrings |
| Appleの複数形リソース用プロパティリスト | xcode-stringsdict | Appleのstringsdict |
| Appleの複数ロケール対応カタログ | xcode-xcstrings | Appleの文字列カタログ |
| GettextのPOカタログ | po | Gettext |
| XLIFF交換用ドキュメント | xliff | XLIFF |
| SubRip字幕 | srt | SubRip |
| 行ごとに翻訳するプレーンテキスト | txt | プレーンテキスト |
| HTMLドキュメントまたはフラグメント | html | HTML |
| ロケールごとに列を設けたCSVテーブル | csv | CSV |
| Javaプロパティのリソースバンドル | properties | Javaプロパティ |
| Payload CMSで選択したフィールド | payload | Payload |
各リファレンスでは、既存のファイルハンドラーについて、抽出と再構築に関する制約も含めて説明しています。CLIとGitHub Appは、Payloadを除き、上記の設定済みの22種類に対応しています。HTMLは.htmlと.htmから判別されます。出力では、変更していないソースをそのまま保持し、明示的に記述された<html>要素のlangをターゲットロケールに設定します。リポジトリ設定では、使用するYAMLの種類またはAndroid形式を明示的に選択してください。Appleの文字列カタログと同様に、CSVもすべてのロケールをソースファイル内に保持します。CLIクイックスタートでは、ひとつのファイルを使い、セットアップから取得までの手順を紹介しています。GitHubでは、マネージド型のリポジトリワークフローを解説しています。
現在のプロバイダー接続では、それぞれの連携仕様に従ってコンテンツを選択し、書き込みます。
構造化データを直接翻訳するには、インラインJSONを送信してください。ソースファイルをアップロードし、フォーマットを保持するには、ファイルドキュメントの手順に従ってください。どちらも翻訳ジョブのライフサイクルは共通です。
ソースのリビジョンと翻訳を対にして管理する #
ファイルの差分翻訳では、現在のソースを以前のソースと比較し、それに対応する既存の翻訳を使用します。これらを組み合わせることで、変更のないメッセージでは承認済みの表現を保持し、新規または変更されたメッセージは翻訳できます。
この比較を有効にするのがキーです。checkout.titleとaccount.titleに同じ英語のテキストが含まれていても、それぞれ異なる翻訳を保持できます。配列内の位置、字幕のキュー番号、プレーンテキストの行位置、ドキュメントの構造も照合に使われます。項目の移動や翻訳済みドキュメントの再構成によって対応関係が変わることがあるため、翻訳は生成元のソースリビジョンと対にして管理してください。
ほとんどのフォーマットでは、翻訳先ロケールごとに別のファイルが生成されます。一方、Appleの文字列カタログでは、各ロケールをソースファイルに統合します。また、Payloadの成果物や文字列カタログには、一部の翻訳先の値が含まれていても、ほかの値が欠けている場合があります。ファイルの有無だけでなく、実際の翻訳先エントリをレビューしてください。
テキストの選択と出力を別々に制御する #
テキストを翻訳対象から除外する方法によって、その扱いは異なります。ロックされたカタログ値にはソースの値を使い、保持対象の値には既存の翻訳先の値を使います。無視対象の値は、出力から除かれる場合があります。利用できる制御方法は、フォーマットと呼び出しインターフェースによって決まります。
JSON/JSONC、YAML、ロケールルート付きYAML、PHP、TypeScriptでは、CLIのキースコープを使用してください。部分更新では、選択範囲外の既存の翻訳表現が保持されます。ただし、ソースにしか存在しないエントリや配列内の位置の扱いは、フォーマットによって異なります。各フォーマットのリファレンスを参照し、結果全体を確認してください。
コンテキストメタデータの扱いにも、それぞれ固有のルールがあります。JSONCの@contextコメントは、その次の文字列値を説明します。ARBの@message.descriptionは、対応するメッセージを説明します。Gettextのmsgctxtは、メッセージを区別し、コンテキストを提供します。通常のコメントは、翻訳指示として扱われなくても、再構成後に保持されることがあります。Reactの@src注釈と@orphan注釈は、カタログの保守ワークフローで使用します。
ファイルを取得したら、実際にそのファイルを使用するシステムで読み込んでください。翻訳の意味に加えて、選択されたロケール、変数、複数形、リンク、保護対象のデータも確認しましょう。ウェブアプリ、ネイティブリソース、静的コンテンツのアプリケーションガイドでは、この作業を完了するための手順を説明しています。