良い実践

ウェブ向け

Markdownパターンを使用することで、読みやすさが向上し、翻訳者にとっても、コンテンツを抽出するウェブサイトのスクリプトにとっても、メンテナンスが容易になります。
多言語サイトでの名前付きアンカーについては、リンクをMarkdownデザインで「ハードコード」するという興味深いアプローチがあります。例：アンカー付きの<h2>タグの場合

現在の言語でのラベル

LLMはリンクを保護する上で人間よりも効率的であり、LSDEは異なる言語バージョン間の問題を検出できます。そうすれば、全ての言語で機能するリンクを共有し、非推奨のアンカーの置換をLSDEで管理できます。

コードの曖昧さ

データ指向モデルを扱う際には、曖昧さを避けてください。例： 悪い実践例： 「key」という用語は明確ではなく、検索が困難になります。

const PRODUCTS: Product[] = [
	{
		id: 'fcf7o',
		logo: '/icons/fcf7o-icon-40.webp',
		label: 'FCF7O',
		key: 'game:fcf7o.words.game_title',
	},
	{
		id: 'lsde',
		logo: '/icons/lsde-icon-40.webp',
		label: 'LSDE',
		key: 'software:lsde.name',
	},
	{
		id: 'lsge',
		logo: '/icons/lsge.webp',
		label: 'LSGE',
		key: 'software:lsge.name',
	},
];

良い実践例： 一貫性のある独自の命名規則を採用してください。「i18nKey」という用語は非常に明確で、正規表現（Regex）を使ってこの値を正確に検索することができます。

const PRODUCTS: Product[] = [
	{
		id: 'fcf7o',
		logo: '/icons/fcf7o-icon-40.webp',
		label: 'FCF7O',
		i18nKey: 'game:fcf7o.words.game_title',
	},
	{
		id: 'lsde',
		logo: '/icons/lsde-icon-40.webp',
		label: 'LSDE',
		i18nKey: 'software:lsde.name',
	},
	{
		id: 'lsge',
		logo: '/icons/lsge.webp',
		label: 'LSGE',
		i18nKey: 'software:lsge.name',
	},
];

怠惰

メモ

悪いアイデアは怠惰から生まれます。

コンテンツを取得するために操作を実行することで、キーを節約しようとしないでください。例：

text

const [title, subtitle] = t( 'game:game.title' ).split( /[:：]/ );

これは誤った良いアイデアです。なぜなら、特定の言語では文字が異なったり、語順が変わったりする可能性があるためです。

タグのフォーマット

デザインのためのコードをテキスト内に直接含めることを最小限に抑え、コードベースからそれを制御できるようにしてください。例えば、画像の場所は指定できますが、そのスタイルやレンダリング方法を指定することはできません。デザインの変更が必要になった場合、単にタグのスタイルを変更するためだけに10言語でテキストを再翻訳することを強制されたくありません！

タグには識別子を含めることができますが、追加情報を加えることは通常、強く推奨されず、悪い実践例とされます。例：次のようにしないでください <img src='url' left /> むしろ <img id=1 /> その後、画像タグのIDを取得し、コードベースで必要なスタイルを適用します。 IDは文字通り使用されるべきであり、そのインデックスを介してではありません。実際、異なる言語では、タグが移動される可能性があり、最初のインデックスと一致しなくなる可能性があります。自然なインデックスの使用は、開発者にとって複雑さを引き起こします。画像やタグがどのインデックスに対応するかを推測しようとすることは、本当に頭を悩ませる問題です。したがって、補間後にタグをカスタマイズできるようにしたい場合は、識別子を持つタグを使用してください。

CSS

サイトの翻訳において、段落がある場合、言語変更時の視覚的なずれを避けるために、翻訳後に最小の高さ（min-height）を選択してください。例：mih={'3lh'} これにより、最も多くの行を占める言語に基づいて最小の高さを定義でき、一貫性のある控えめなユーザーエクスペリエンス（UX）が保証されます。

名前空間

翻訳キーには常に「namespace」を含めてください。たとえ1つしかなかったとしてもです。これにより、キーを見つけるためのRegexパターンを設定するのが非常に容易になります。例：game:a.b.c、common:a.b.c

GIT バージョン管理

.lsde プロジェクトは JSON 形式のファイルであるため、Git などのツールを使用したバージョン管理が容易です。完全な履歴の保持とセキュリティ向上のため、プロジェクトを Git リポジトリに保存することを強く推奨します。 LSDE には独自のバックアップシステムが統合されていますが、データファイルの管理には Git の使用が最適なソリューションです。

文脈とライティング

各キーに明確な文脈を提供する 明確な文脈（コンテキスト）は、キーの名前、アクセスパス（階層）、隣接する要素（親キーや子キー）、またはメタデータの中に存在させるべきです。推測の余地を与えるような曖昧なキーは避けてください。コード内での用途を確認しなければキーの意味が理解できない場合は、データ構造の設計を改善する必要があります。

明確なキーの例：game:.scenes.001.events.001.1game:.scenes.001.events.001.2game:.scenes.the-ice-land.events.the-lost-house.1game:.scenes.the-ice-land.events.the-lost-house.2game:.ui.menus.new-game.labelgame:.ui.menus.new-game.description

これらのキーにより、それらがダイアログやインターフェース要素を指していることが即座に理解できます。

最初の2つは数値識別子（IDs）を使用しています。これは、アートディレクション（DA）が柔軟で、技術的な構造に影響を与えずに進化する可能性があるアクションゲームにおいて効率的なアプローチです。
次の2つはセマンティック（意味的）IDを使用しています。これは、コンテンツがコードと密接に関連しているナラティブゲームにおいて不可欠です。これにより、物語とゲームロジックの結合を損なうことを防ぎます。
最後の2つは、メニュー要素（ラベルと説明）を明確に記述しています。

悪い習慣の例：game:events.001.1（曖昧すぎる：このイベントはどこで使用されるのか？） game:.scenes-events-the-lost-house.1（パス内の冗長性） game:.ui-menus.new-game-label（不必要な連結）

パス内での冗長性は避けてください。検索を容易にする必要がある場合は、JSON データの構造を崩すのではなく、連結されたキーを含む型ファイルを書き出す（エクスポートする）ようにしてください。

暗黙の文脈への依存を避ける 文字列は、理解するために外部要素（画面上の位置、色、アイコンなど）に依存してはなりません。例：以下の表現は避けてください。 「ここをクリックして続行」 以下のように記述してください。 「支払いへ進む」 テキストは、ユーザーインターフェース（UI）から切り離された状態でも理解可能である必要があります。言語によっては、適切な翻訳が存在しなかったり、アクションやテキストの配置によって言い回しが異なったりする場合があります。

メモ

アクションテキストは、「ここをクリック」や「詳細」のように内容を特定できないものではなく、「支払いへ進む」、「PDFレポートをダウンロード」のように、アクションと対象を明記する必要があります。

分割された文章と過度なモジュール化を避ける プログラミングの原則（S.O.L.I.D. など）を i18n コンテンツの作成にそのまま適用しないでください。ライティングとコーディングは異なる分野です。言語ごとに固有の構文があるため、断片的なフレーズではなく、完全な文章を優先してください。 i18next のようなフレームワークはネスト（階層化）をサポートしていますが、それはしばしば不必要な複雑さを生みます。バリエーションが必要な場合は、文章全体を書き直してください。インターポレーション（変数の挿入）は、名前や数値などの単純な変数のみに限定してください。
表示上の制約 (UI) を明示する インターフェースに文字数制限や長さの制約がある場合は、メタデータに明記し、ビジュアル（スクリーンショットやモックアップ）を提供してください。プログラマーが世界中のすべての言語に合わせて UI を動的に調整するよりも、翻訳者が制限されたインターフェースに合わせてテキストを調整する方が簡単です。この管理をライターに委ねることで、より優れたユーザーエクスペリエンス（UX）が保証されます。
制御されていない絵文字の禁止 テキスト内に特殊文字や絵文字を直接挿入しないでください。コードを介してレンダリングを制御できるよう、変数（例：{{emoji_heart}}）を使用してください。絵文字の表示は、OS やユーザーの環境によって大きく異なります。
文化的メタファーを避ける 慣用句、言葉遊び、現地のメタファーは、汎用的な文字列では避けるべきです。ある言語では明確な表現も、別の言語では意味不明であったり翻訳不可能であったりすることがあります。
翻訳者がアプリケーションを見ていないことを前提とする 翻訳者がコードにも UI にもアクセスできないものとして執筆してください。理解に必要なすべての情報は、キー、その階層、またはメタデータの中に含まれている必要があります。

I18n テクニック

明示的で名前付きのプレースホルダー 位置インデックス ({0}, {1}) よりも、名前付きプレースホルダー ({username}, {count}) を優先してください。LSDEは、コンテキストを定義し、プロジェクト内での追跡可能性を確保するための変数専用セクションを提供しています。
1つのコンセプトにつき1つのプレースホルダー 各プレースホルダーはアトミック（原子状）であり、単一のデータ（名前、日付、数値など）を表す必要があります。翻訳や解釈を困難にする、汎用的または多態的な変数は避けてください。
RTL (Right-to-Left) への対応 右から左に書く言語の表示を想定してください。文字列を手動で修正することなく、レンダリングがスムーズで構造的に正しい状態を維持する必要があります。
連結の禁止 複数の翻訳キーを組み合わせて文章を構成しないでください。各言語固有の構文や文法的な一致を尊重するため、完全な一文はすべて単一のキーに対応させる必要があります。

良い実践 ​

ウェブ向け ​

現在の言語でのラベル ​

コードの曖昧さ ​

怠惰 ​

タグのフォーマット ​

CSS ​

名前空間 ​

GIT バージョン管理 ​

文脈とライティング ​

I18n テクニック ​