HTML
変更対象外のソースをそのまま保持し、文書の言語を翻訳先ロケールに設定しながら、HTMLのテキストと属性を翻訳します。
HTMLは、リンクや動作、アクセシビリティ情報を担う構造の中に、人が読むテキストを配置する形式です。htmlハンドラーは、対応するテキストのまとまりと説明用の属性を選び、単一の翻訳先ロケール向けの訳文を元のソースに反映します。多言語ページをロケールごとの領域に分割することはありません。
入力文書の構造を保持する #
文書では、元の文書型宣言と明示的に記述された要素が保持されます。フラグメントはフラグメントのまま扱われ、翻訳時に<html>、<head>、<body>のラッパーが追加されることはありません。コメント、変更対象外の属性、引用符の形式、翻訳対象範囲外の空白は、ソースに記述されたとおりに保持されます。
明示的に記述された<html>要素では、既存のlangの値が翻訳先ロケールに置き換えられます。属性がなければ、lang属性が追加されます。たとえば、フランス語への翻訳では<html lang="en">が<html lang="fr">になります。明示的な<html>要素のないフラグメントに、言語を指定するためだけにその要素が追加されることはありません。
たとえば、次のフラグメントには、画面に表示されるテキストとアクセシビリティ用のテキストが含まれています。
<section>
<h2>Delivery options</h2>
<p>Read the <a href="/delivery">delivery policy</a>.</p>
<img src="/truck.svg" alt="Delivery truck" />
<input placeholder="Enter your address" aria-label="Delivery address" />
</section>見出し、段落、リンクのラベル、画像の代替テキスト、入力欄のプレースホルダー、ARIAラベルは、翻訳対象のテキストです。リンク先と画像の参照元は、構造を定義するプロパティとしてそのまま保持されます。このフラグメントを翻訳しても、ローカライズされたリンクの作成や画像素材の置き換えは行われません。
属性と領域の選択 #
標準で対応している属性には、画像のaltとtitle、入力欄とテキストエリアのplaceholderとtitle、一部のtitle属性、メタ要素のcontent、ARIAラベル属性があります。メタデータは慎重に確認してください。属性を名前で選択しても、その値がすべて文章とは限りません。コンポーネントのプロパティルールを設定すると、名前を指定した要素の属性を翻訳対象に追加できます。
スクリプト、スタイル、整形済みコード、コード、数式、テンプレート、スクリプト無効時の代替表示、テキストエリアの内容は、通常のテキスト抽出の対象外です。抽出対象外の要素でも、対応する説明用の属性があれば処理の対象になります。SVGでは、任意の描画データを翻訳するのではなく、対応するtitle、desc、textの内容を専用の仕組みで選択します。
インラインのマークアップと{{...}}トークンは、テキストの翻訳中はプレースホルダーで保護され、再構築時に翻訳済みの範囲内に復元されます。出力結果の要素構造を確認し、アプリケーションで使う代表的な値を変数に入れて、表示を確認してください。
再利用とソースを保持した出力 #
再利用するには、以前の原文と訳文で、テキストとプレースホルダーの構造が対応している必要があります。ハンドラーは両者の対応関係を確認し、曖昧な組み合わせを拒否することがあります。無関係なページの表示結果を比較するのではなく、採用した訳文を、対応するソースのリビジョンに紐付けて管理してください。
変更されるのは、翻訳対象の範囲と、明示的に記述された<html>要素の言語属性だけです。それ以外のソースは、そのまま出力結果にコピーされます。ハンドラーは、信頼できないHTMLの無害化は行いません。アプリケーション側でのセキュリティチェックと表示の検証は、引き続き実施してください。
不正な入れ子構造によって、パーサーが無関係なマークアップをまたいでテキストを結合してしまう場合、ハンドラーは曖昧な訳文を書き込まず、文書を拒否します。入れ子構造を修正してから再試行してください。HTMLの規則に従ってタグが省略されている場合は、文書の基本構造を追加する必要はありません。
CLIまたはGitHub AppでHTMLファイルを設定する #
CLIとGitHub Appは、.htmlと.htmからhtmlを推定します。生成される翻訳先ファイルがソースの選択パターンに含まれないようにし、.lingo/config.jsonでソースファイルを選択してください。
{
"sourceLocale": "en",
"targetLocales": ["fr"],
"files": [
{ "pattern": "pages/en/**/*.html", "format": "html" },
{ "pattern": "pages/en/**/*.htm", "format": "html" }
]
}これらの拡張子では、formatの明示的な指定は任意です。CLIの設定でプロジェクトを組織とローカライゼーションエンジンに紐付けるか、GitHub Appで使うエンジンを指定してください。翻訳先はそれぞれ、pages/fr/index.htmlのようにロケールごとの個別ファイルになります。HTMLはキー単位の翻訳に対応していません。
取得後は、文書またはフラグメントを実際の利用先で表示してください。リンクとテキスト以外の属性を比較し、画面上のテキストとあわせてアクセシビリティ用のテキストも確認してください。CMSからHTMLを取得する場合は、そのコネクターのフィールド選択と書き戻しの手順に従ってください。実装の一部でHTMLを処理していても、受け付ける入力はコネクターによって異なる場合があります。