CSV
指定した列をキーに、ロケールごとの列を一つのファイルにまとめたCSVテーブルを翻訳します。
CSV翻訳テーブルでは、原文とすべての翻訳を一つのファイルにまとめ、メッセージごとに一行、ロケールごとに一列を使います。csvファイルハンドラーは、ファイル内の翻訳先ロケールのセルを埋め、結果を元のパスに書き戻します。書き込むのは翻訳先ロケールのセルだけで、該当するロケールの列がなければ追加します。詳しくは翻訳される行を参照してください。他の列、行の順序、引用符、改行コードはそのまま保持されます。ファイル先頭のUTF-8のバイトオーダーマークは保持されず、書き込み後のファイルには付与されません。そのため、このマークでUTF-8を判別する表計算アプリでは、文字コードにUTF-8を指定してファイルをインポートする必要がある場合があります。
テーブルを構成する #
空行でも空白文字だけの行でもない最初の行が、ヘッダーになります。各行を識別するキーの列と原文の列を一つずつ用意し、翻訳先ロケールごとに専用の列を設けます。
id,en,notes,de
checkout.title,Complete your order,Shown on the last step,Bestellung abschließen
checkout.pay,"Pay now, or later",,- ロケール列。 ヘッダーがロケールコードと一致する列は、そのロケールの列として扱われます。大文字と小文字は区別しません。
deとDEはどちらもドイツ語の列ですが、de-DEは別のロケールです。原文の列のヘッダーには、設定のsourceLocaleを使います。 - キー列。 既定では、ヘッダーの最初のセルがキー列の名前になります。別の列を使うには、ファイルの設定項目で
keyColumnを指定します。原文をキーとして使う場合は、原文の列をそのままキー列にできます。 - その他の列。
notesなど、キー列でもロケール列でもない列は、バイト単位でそのまま保持され、翻訳には送信されません。 - 構文。 セルはカンマで区切ります。カンマ、引用符、改行を含むセルは二重引用符で囲み、その中の引用符は二つ重ねて記述します(
"")。セミコロン区切りやタブ区切りのファイルには対応していません。
CSV翻訳を設定する #
CSVファイルが選択されるのは、ファイルの設定項目のパターンが.csvで終わり、そこから形式が判別される場合か、"format": "csv"が設定されている場合だけです。"format": "csv"を指定した設定項目では、.csvファイルだけが選択されます。data/**/*のように対象範囲の広いパターンでも、この形式を指定しなければCSVファイルは選択されません。そのため、既存の設定項目で無関係なデータファイルが書き換えられることはありません。拡張子は大文字と小文字を区別します。strings.CSVという名前のファイルは翻訳されないため、strings.csvに変更してください。
{
"sourceLocale": "en",
"targetLocales": ["de", "fr"],
"files": [{ "pattern": "i18n/strings.csv", "keyColumn": "id" }]
}すべてのロケールでファイル自体が出力先になるため、この形式ではtargetPathは使用できません。CSVの行はキーの制御設定との照合対象にならないため、lockedKeys、preservedKeys、ignoredKeysも使用できません。CLIとGitHub Appで同じ設定を使えます。
翻訳される行 #
| 行 | 結果 |
|---|---|
| キーと原文がある | ロケールのセルが空か、翻訳が古くなっている場合に翻訳されます。 |
| キーがあり、原文のセルが空 | そのまま保持され、ロケールのセルは変更されません。 |
| 原文があり、キーのセルが空かスペースのみ | そのまま保持され、翻訳されません。翻訳するにはキーを設定してください。 |
| キーと原文がどちらも空、または空行 | スペースだけの行も含め、そのまま保持されます。 |
スペースだけのロケールのセルは、空として扱われます。入力済みのセルは、その行の原文が前回のプッシュ以降に変更されていなければ再利用されます。原文が変更されると、その行のすべてのロケールのセルが再翻訳されます。前回のプッシュ以降に追加された行では、入力済みのセルは保持され、空のセルだけが翻訳されます。キーが変更された行は、追加された行として扱われます。ファイルを初めてプッシュする場合、CLIで--forceを使用する場合、GitHub Appのコマンドで--forceを指定せずにファイルを指定する場合も、入力済みのセルは保持されます。また、原文の列やキー列の名前を変更した場合など、前回プッシュしたファイルで比較対象となる原文の列またはキー列を一つに特定できない場合も同様です。GitHub Appのコマンドで--forceを指定すると、ファイル内のすべての行が再翻訳されます。
次の条件に当てはまる原文は、翻訳せずにそのままコピーされます。100のように、アスキー文字の数字0〜9だけで構成されるテキスト。//で始まるか、英字・数字・アンダースコアで構成されるスキームの後に://が続くURLで、かつ//より後のアドレスがlocalhostで始まるか、1文字以上の文字、ドット、さらに2文字以上の文字が続く部分を含むもの(例:https://lingo.dev/docs)。英字と数字だけで構成され、大文字・小文字・数字をそれぞれ1文字以上含む22文字の識別子。2024-01-15や2024-01-15T10:00:00ZのようなISO 8601形式の日付または日時。原文は、その行のすべての翻訳先ロケールのセルにコピーされ、既存の内容を上書きします。その行は翻訳に送信されず、課金もされません。1.5、100%、メールアドレス、15.01.2024のような別形式の日付など、その他の値は翻訳されます。また、mailto:とtel:のリンク、git+ssh://のようにスキームに上記以外の文字を含むURL、https://intranetやhttps://a.bのようにアドレスがlocalhostで始まらず、上記の条件を満たすドットも含まないURLも翻訳されます。
翻訳先ロケールの列がなければ、ヘッダーの末尾に追加されます。新しい列が複数ある場合は、ロケールコードのアルファベット順に追加されます。その後、各行の列数が揃うように、すべての行に空のセルが補われます。行の並べ替え、追加、削除は行われません。
エラー #
次の場合は、翻訳や課金が発生する前にファイルの処理が失敗し、問題を示すメッセージが表示されます。
- 設定した
keyColumnがヘッダーにない場合、またはヘッダーの最初のセルが空で、keyColumnも設定されていない場合。 - 二つの行に同じキーがある場合。翻訳が誤った行に格納されるのを防ぐためです。
- ヘッダーに原文ロケールの列がない場合。
- キー列が翻訳先ロケールの列も兼ねている場合。
- 設定した
keyColumn、原文ロケール、または翻訳先ロケールの名前が、ヘッダーに複数回出現する場合。 - ヘッダーよりセル数の多い行がある場合。
- 引用符で囲まれたセルが閉じられていない場合。
- 同じセル内で、閉じ引用符の後にテキストが続いている場合。
ファイルを修正して、もう一度プッシュしてください。CLIでは、メッセージはロケールごとではなく、ファイルの下に一度だけ表示されます。実行全体が失敗した場合は、最後のRun failed:行に同じメッセージが再表示されます。GitHub Appでは、チェック実行に表示されます。
既存の翻訳を修正する #
文言を思いどおりに変更するには、セルを直接編集します。一つの翻訳だけを再生成するには、そのセルを空にし、行の他の部分はそのままにして、通常のプッシュを実行します。
lingo push --waitCLIの--forceは、アップルの文字列カタログと同様に、入力済みのセルを再利用します。--keyでCSVファイルの対象を絞り込むことはできません。CLIではエラーでプッシュが停止し、GitHub Appではそのファイルがスキップされます。CLIのパージでは、原文と出力先が同じパスを使うため、そのファイルがスキップされます。コミットする前に、ファイル全体の差分をレビューしてください。