Markdoc

アノテーション、変数、コードを保持しながら、Markdocの本文と選択した文字列属性を翻訳します。

Markdocのアノテーションは、文書の本文をカスタムコンポーネントや変数と結び付けます。markdocファイルハンドラーは、レンダラーに必要なアノテーションを保持しながら、対応する本文と、選択した文字列型のタグ属性を翻訳します。

表示用のタグプロパティを選択する #

文書には、表示用のメタデータ、固定のレイアウト識別子、コールアウトを組み合わせられます。

markdown
---
title: Delivery options
description: Understand the available delivery methods.
layout: article
---

{% callout title="Delivery deadline" type="warning" %}
Confirm your address before checkout.
{% /callout %}

段落と、既定で選択されるフロントマターのtitleおよびdescriptionはテキストです。タグのtitleは、プロパティルールで選択すると翻訳対象になります。type="warning"とlayout: articleは構造上の識別子です。これらを利用する側で翻訳済みの値が明示的に求められている場合を除き、選択しないでください。

ルールでは、プロパティ名をすべてのタグに適用することも、指定した名前のタグだけに限定することもできます。同じ属性がタグによって異なる目的で使われる場合は、対象のタグを限定する形式をおすすめします。数値、真偽値、変数に由来する属性、その他の文字列以外の属性は、本文としてそのまま翻訳する対象にはなりません。

保護される要素 #

コードフェンス内のコードとインラインコードは翻訳対象外です。リンクの表示テキストは変更できますが、リンク先は保持されます。本文中のインラインアノテーションと画像は、構文要素として保護されます。タグ名と未選択の属性は、そのまま文書に残ります。ハンドラーは、翻訳済みの文字列属性をMarkdocの引用符の規則に合わせてエスケープしますが、レンダラーのカスタムタグ用スキーマを提供するものではありません。

フロントマターのtitleとdescriptionは既定で選択されます。フロントマターの選択を空にすると、これらは変更されません。マップまたはシーケンスを選択すると、その配下のスカラー値も対象になります。隣接するルーティング用フィールドやコンテンツ識別子を変更せずに保持する必要がある場合は、seo.titleのようにパスを的確に指定してください。

原文と訳文の対応関係を維持する #

再構築では、現在の原文内のテキスト範囲を置き換えます。その際、対応関係が保たれた以前の原文と訳文から、表現を再利用することもできます。保護されたインライン構造の対応関係を安全に確認できない場合は、再利用に失敗することがあります。特にタグの移動やリンクの変更を行った後は、承認済みの訳文に対応する原文のリビジョンを保持してください。

Markdocのアノテーションを含む.md文書でも、このハンドラーが選択されるとは限りません。CLIは.mdをMarkdownと判定するため、文書の言語仕様上、Markdocとしての処理が必要な場合は、形式を明示的に選択してください。

Markdocの翻訳を設定する #

CLIは.mdocから形式をmarkdocと判定します。キーのスコープ指定は利用できません。フロントマター、タグプロパティの選択、出力先のレイアウトはCLIの設定で指定し、リポジトリのワークフローにはGitHubを使用してください。

サイトのスキーマで検証する #

ファイルハンドラーは、フレームワークのルート、コンテンツの読み込み、アプリケーションのMarkdoc変換を設定するものではありません。取得後は、原文と同じスキーマで訳文を解析し、レンダリングしてください。翻訳済みの段落と併せて、表示用の属性、リンク先、変数、選択したフロントマターを確認してください。