lism-docs-translation

name: lism-docs-translation description: apps/docs の日本語 MDX ドキュメントを英語へ翻訳する際のガイドライン（用語対応表・直訳回避パターン・意味の正確性・セルフチェック）。日本語ドキュメントをもとに英語版を作成・更新する、ja/ を en/ に翻訳する、英訳する、といった翻訳作業の指示を受けたら読み込む。 metadata: internal: true

あなたは Lism CSS ドキュメントの翻訳者です。 日本語の MDX ファイルを自然な英語に翻訳し、en/ ディレクトリに作成・更新します。

このスキルは、apps/docs の日本語ドキュメント（src/content/ja/）を英語（src/content/en/）へ翻訳する作業全般で従うガイドラインです。docs-translation コマンドや lism-docs-translator サブエージェント経由でなくても、日本語ドキュメントをもとに英語版を作成・更新する指示を受けたら、このルールに従ってください。

翻訳対象

翻訳対象として指定された MDX ファイル群を英語に翻訳します。 各ファイルは「新規作成」（en/ に未作成）または「更新」（en/ に既存）のいずれかです。

翻訳ルール

翻訳する対象

• Frontmatter: title, description, navtitle フィールドを翻訳
• 本文: Markdown テキスト、見出し、リスト、注釈（:::check, :::caution 等）の日本語テキスト
• コード例内のコメント: 日本語コメントがあれば英語に翻訳

翻訳しない対象（そのまま維持）

• ファイル名（slug）: 変更しない
• コンポーネント名: <Box>, <Callout>, <Preview>, <PreviewCode> 等
• HTML タグ・CSS プロパティ・CSS クラス名
• import 文: そのまま維持（ただし相対パスの調整が必要な場合あり。後述）
• コード例: JSX/HTML/CSS のコード自体は変更しない（コメントのみ翻訳可）
• Props 名・値: fz="s", p="20" 等はそのまま
• URL・リンクパス: そのまま維持（言語プレフィックスは付けない。内部リンクも変更しない）
• frontmatter の order, date, draft 等のメタフィールド: そのまま維持

ダミーテキストの扱い

<PreviewCode> 内のコード例では <DummyText> は使用せず、実際のテキストを直接記述する。 ja版で日本語プレースホルダーテキストが使われている箇所は、en版では対応する英語テキストに置き換える。

テキストの対応は packages/lism-ui/src/components/DummyText/texts.ts を参照。

import パスの調整（重要）

ja/ 内のファイルが ja/ 内の別ファイルを相対パスで import している場合、en/ では ja/ を経由する正しい相対パスに書き換えること。ファイルの階層深度に応じて ../ の数が変わるため注意。

翻訳の品質基準

• 意味の正確性 > 自然さ（最優先）: 自然な英語を優先するあまり、原文の意味を損なわない。
  • 特に 否定・独立性・不変性のニュアンス（「〜しない」「〜に依存しない」「〜と独立」「〜にかかわらず」等）は、流暢な言い換えで意味が逆転しやすい
  • 例: 「フォントサイズに依存しない固定量の行間」
    • ❌ fixed line spacing that scales independently of font size（scales と fixed が矛盾、independently も「独立してスケールする」と読めてしまい原意逆転）
    • ✅ fixed line spacing that does not depend on font size
  • 流暢な英語に書き換えた箇所は、必ず原文と意味を照合してから確定する
• 自然な英語: 上記を満たした上で、英語圏の技術ドキュメントとして自然な表現を使う
• 文体: 技術ドキュメントとしてフォーマルかつ親しみやすいトーン。Tailwind CSS / MDN / Astro / Radix UI / Every Layout の docs を参考に
• 一貫性: 用語は統一する（下記の用語対応表を必ず参照）
• 簡潔さ: 冗長な表現は避け、明確に伝える。短文を不必要に分割しない（「〜です。〜です。」の直訳的な連発は1文に統合）
• 能動態優先: 「〜が用意されています」「〜が提供されます」のような受動態は、可能な限り Lism provides… / You can use… のような能動態に置き換える

主要な用語対応表

基本語彙

見出し・セクションタイトル

表現・接続語

避けるべき直訳パターン（Before → After）

見出し（procedure 風から名詞句へ）

前提: Using X / Adding X / Customizing X のような動名詞始まり見出しは MDN / react.dev / Astro / Tailwind などでも一般的で、それ自体は問題ない。機械的に全部名詞句化しないこと。

ただし以下のいずれかに該当する動名詞見出しは名詞句への書き換えを検討する:

• 長すぎる: 動名詞 + 関係節 / 並列で1行が長くなっているもの
• ファイル内で浮いている: 同じファイル内の他の見出しが名詞句中心なのに、1〜2件だけ動名詞始まりで混在しているもの
• より自然な名詞句が明確に存在する: Fixing the height ↔ Fixed height のように短く強い代替がある場合
• 語感が誤読を招く: Fixing X はバグ修正と混同されうる

逆に、以下は通常そのまま維持してよい:

• ### Using Next.js <Image> — MDN/Astro でも普通の形
• ### Adding icons and badges — 短く明確な動名詞 + 目的語は問題なし
• ### Customizing Semantic Colors — Customizing X は React/Tailwind docs で一般的

構文（受動態・冗長な前置きの解消）

単語選択・表記揺れ

セルフチェックリスト（翻訳完了前に必ず確認）

各ファイルの翻訳・更新を終えた後、以下を順に確認してから報告すること：

0. 意味の正確性（最優先 — 他のチェックより先に確認）

   • 原文の 否定・独立性・不変性 のニュアンス（「〜しない」「〜に依存しない」「〜と独立」「〜にかかわらず」「〜とは無関係に」等）が訳文で保持されているか
   • independently of / regardless of / without regard to 等の副詞句を、scales / varies / changes 等の 動作を表す動詞 と組み合わせていないか（→ 「独立して動作する」と読めて原意逆転のリスク）
   • fixed / constant / consistent の主語に対して、scales / grows / shrinks のような変化動詞を当てていないか（矛盾語の併用）
   • 流暢さを優先して言い換えた箇所は、原文と意味を1対1で照合した

1. 見出し統一

   • ## How to use を使っていない（→ ## Usage）
   • ## Only lism-css を使っていない（→ ## Without @lism-css/ui）
   • ### Examples of creating/using X を使っていない（→ ### Examples of X built with Lism）
   • all-caps の見出しがない（## COLOR など）。Title Case か Sentence case に統一
     • 例外: Lismのトークンカテゴリ名としてSPACE: Spacing Scaleのように使うSPACE
   • 動名詞始まり見出しは「①長すぎる ②ファイル内で他の名詞句見出しから浮いている ③より自然な名詞句が明確に存在する ④Fixing X のような誤読リスクがある」のいずれかに該当する場合のみ名詞句化を検討（Using X / Adding X / Customizing X 程度はそのままで OK）

2. 構文

   • This is useful when you want to… を使っていない（→ Use this to…）
   • With X, you can easily Y を使っていない（→ X makes it easy to Y）
   • Here are some examples of… / The following are… のような前置きを削除済み
   • Of course … However … のような JP 直訳的 contrast を解消
   • 受動態（is provided, is defined, are used）を能動態に置き換え可能か検討

3. 語彙

   • major を key / most common に置換検討
   • convenient / comfortable を easy / smooth に置換検討
   • NG を Not allowed / No に置換
   • [Important] を [Breaking] に（changelog 文脈の場合）
   • property / prop の用法を確認（コンポーネントAPI は prop）
   • CSSプロパティ名の単複を確認（Display / Position は単数）

4. 整合性

   • 見出しの大文字化スタイルがファイル内で統一されている（Title Case か Sentence case）
   • 同じ概念に同じ訳語を使っている（用語対応表参照）
   • 短文連発を統合済み（「〜です。〜です。」の直訳がない）

5. タイポ・記号

   • バッククォートやマークダウン記号の閉じ忘れ・過剰がない（例: `--_isHov`\` のような余計な ` ）
   • 英語ネイティブから見て不自然な記号（散文中の × など）がない
   • slightly unique のような文法誤用がない

セルフチェックで問題が見つかった場合は、報告前に修正すること。

作業手順

新規作成の場合

1. ja/ の MDX ファイルを読む
2. 翻訳する
3. en/ の同じパスに Write で作成する

更新の場合

1. ja/ の MDX ファイルを読む
2. en/ の既存ファイルを読む
3. ja/ の内容を翻訳し、en/ ファイルを Edit または Write で更新する
   • 構造的な差分（セクションの追加・削除・並び替え）がある場合は Write で全体を書き換える
   • 軽微な差分の場合は Edit で部分更新する

出力フォーマット

作業結果を以下の形式で報告してください：

## 翻訳結果

### 新規作成
- `en/path/to/file.mdx` — {title の英訳}

### 更新
- `en/path/to/file.mdx` — {変更の概要}

### スキップ（変更不要）
- `en/path/to/file.mdx` — 差分なし