マークダウン

コードやリンク、承認済みの訳文を再利用するために必要な構造を保ちながら、文書の本文と選択したフロントマターを翻訳します。

マークダウン文書は、説明文と、読者の理解を助ける構造で成り立っています。mdファイルハンドラーは、コードとリンク先を保護しながら、見出し、段落、表のセル、対応しているディレクティブのラベル内の文章を翻訳します。翻訳後もマークダウン形式が保たれるため、既存のレンダラーをそのまま使えます。

テキストと保護対象の構造 #

たとえば、リンク先と関数名はそのままに、リンクのラベルを変更できます。

markdown
---
title: Delivery options
description: Choose how your order arrives.
slug: delivery
---

## Choose delivery

Read the [delivery policy](/policies/delivery) before calling `confirmOrder()`.

見出し、段落の文章、リンクのラベルはテキストとして扱われます。一方、リンク先とインラインコードは保護対象の構造です。通常の文書プロファイルでは、コードフェンスで囲まれたコードと生のHTMLは、文章の抽出対象に含まれません。原文がHTML文書の場合はHTMLを、独自のMarkdocタグが文書言語の一部となっている場合はMarkdocを使用してください。

フロントマターの選択 #

既定では、ファイルハンドラーはtitleとdescriptionを選択します。それ以外のフィールドは、明示的に選択しない限り変更されません。translateFrontmatterFieldsを空のリストにすると、フロントマターは翻訳対象から外れます。フィールドは内容に応じて選択してください。読者向けの見出しは翻訳できますが、スラッグ、コンポーネント識別子、ルーティングキーは、そのまま保持する必要がある場合があります。

対応しているフィールドパスでは、シーケンスの要素を含む、入れ子になった値を指定できます。マップやシーケンスを選択すると、その配下のスカラー値も対象になります。隣接するルーティング用フィールドを変更せずに保持する必要がある場合は、seo.titleのように対象を絞ったパスを選択してください。使用するインターフェースのフロントマターオプションで、翻訳するテキストを選択します。

再利用には文書間の対応が必要 #

ハンドラーは、テキストの各単位を以前の原文とそれに対応する訳文に照合し、変更された訳文を現在の原文の構造に挿入します。既存の訳文を再利用できるのは、対応関係が明確な場合に限られます。以前の原文と訳文で、保護対象のインライン構造が異なると、構造の不一致により再利用できないことがあります。

承認済みの訳文に対応する原文のリビジョンを保持してください。訳文だけを再構成した場合は、差分更新を依頼する前に、対応する原文と構造をそろえてください。サイトのマークダウン処理ツールで翻訳結果をビルドし、マークダウンの仕様ごとに異なる構文を確認してください。

文書の設定とレンダリング #

CLIは.mdからmdを推定します。CLIの設定でファイルの選択、フロントマターのフィールド、出力先パスを設定できます。または、GitHubを使ってリポジトリの翻訳を管理することもできます。マークダウンでは、CLIのキースコープは使用できません。

サイトのマークダウン処理ツールで出力をレンダリングしてください。翻訳されたメタデータ、リンク、見出しのフラグメント、コード例をあわせて確認します。/policies/deliveryを保持しても、そのページの別言語版が作成されるわけではありません。静的コンテンツガイドでは、出力先パスをサイトのローダーやロケール別のルートに結び付ける方法を説明しています。