# Lism Docs Translation > apps/docs の日本語 MDX ドキュメントを英語へ翻訳する際のガイドライン（用語対応表・直訳回避パターン・意味の正確性・セルフチェック）。日本語ドキュメントをもとに英語版を作成・更新する、ja/ を en/ に翻訳する、英訳する、といった翻訳作業の指示を受けたら読み込む。 Use when this capability is needed. - Skill: `tomevault-io/lism-docs-translation` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/lism-docs-translation` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/lism-docs-translation/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Web & Frontend - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/lism-docs-translation --- あなたは 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）**: 変更しない - **コンポーネント名**: ``, ``, ``, `` 等 - **HTML タグ・CSS プロパティ・CSS クラス名** - **import 文**: そのまま維持（**ただし相対パスの調整が必要な場合あり。後述**） - **コード例**: JSX/HTML/CSS のコード自体は変更しない（コメントのみ翻訳可） - **Props 名・値**: `fz="s"`, `p="20"` 等はそのまま - **URL・リンクパス**: そのまま維持（言語プレフィックスは付けない。内部リンクも変更しない） - **frontmatter の `order`, `date`, `draft` 等のメタフィールド**: そのまま維持 ### ダミーテキストの扱い `` 内のコード例では `` は使用せず、実際のテキストを直接記述する。 ja版で日本語プレースホルダーテキストが使われている箇所は、en版では対応する英語テキストに置き換える。 テキストの対応は `packages/lism-ui/src/components/DummyText/texts.ts` を参照。 | サイズ | 日本語 | 英語 | |--------|--------|------| | xs | ロレム・イプサムの座り雨。 | Lorem ipsum dolor sit amet. | | s | xs + 目まぐるしい文章の流れの中で、それは静かに歩く仮の言葉です。 | xs + Consectetur adipiscing elit, sed do eiusmod tempor Incididunt ut. | | m | s + Elitも穏やかに続いていきますが、積み重ねられてきた「LiberroyとFoogの取り組み」は、余白のようなものです。 | s + Labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut. | | l | m + 作業が進むにつれて... | m + Aliquip ex ea commodo consequat... | ### 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…` のような能動態に置き換える ## 主要な用語対応表 ### 基本語彙 | 日本語 | 英語 | |--------|------| | コンポーネント | component | | トークン | token | | 余白トークン/スペーシングトークン | spacing tokens（タイトル・見出しでは `Spacing Tokens`） | | SPACEトークン | `SPACE` token(s)（Lismの固有カテゴリ名として明示する場合のみ。一般説明では spacing tokens） | | 余白のスケーリング | `Spacing Scale`（`SPACE`見出しでは`SPACE: Spacing Scale`） | | プリミティブ | primitive | | レイアウト | layout | | ユーティリティ | utility | | プロップ / Props | prop / props（**property ではない** — JSX/React 文脈では prop が標準） | | 読み込む | import / load | | 出力 | output | | 初期値 / デフォルト値 | default value | | 省略可 | optional | ### 見出し・セクションタイトル | 日本語 | 英語 | |--------|------| | 使い方 | **Usage**（× How to use） | | lism-css のみ／lism-css だけ | **Without @lism-css/ui**（× Only lism-css） | | 〜の例／〜の作成例 | **Examples** / **Examples of X built with Lism**（× Examples of creating X / Examples of using X to display Y） | | 〜について | （セクションタイトルでは省略：× About X → ✅ X） | | レスポンシブ対応 | Responsive styling（× Responsive support） | | 利用ガイド | Choosing a X（× Usage guide for X） | ### 表現・接続語 | 日本語 | 英語 | |--------|------| | 〜したい時に便利 | Use this to… / This lets you…（× This is useful when you want to…） | | 〜を使うと簡単に〜できます | X makes it easy to Y / X lets you Y（× With X, you can easily Y） | | 以下が〜の例です／〜は次の通り | （前置きを削除して直接本題へ） | | もちろん〜、ただし〜 | （直接 contrast を導入。× Of course X. However Y.） | | 主要な | most common / key / primary（× major） | | 便利な／快適な | easy / smooth / productive（× convenient / comfortable） | | NG | Not allowed / No（× NG — 和製英語、英語docsで通じない） | | 重要 [変更履歴文脈] | **[Breaking]**（× [Important]） | | 前半／後半 | first part / second part（× front half / back half） | | 基本的に | generally（× basically — filler） | ## 避けるべき直訳パターン（Before → After） ### 見出し（procedure 風から名詞句へ） **前提**: `Using X` / `Adding X` / `Customizing X` のような動名詞始まり見出しは MDN / react.dev / Astro / Tailwind などでも一般的で、それ自体は問題ない。機械的に全部名詞句化しないこと。 ただし以下のいずれかに該当する動名詞見出しは名詞句への書き換えを検討する: - **長すぎる**: 動名詞 + 関係節 / 並列で1行が長くなっているもの - **ファイル内で浮いている**: 同じファイル内の他の見出しが名詞句中心なのに、1〜2件だけ動名詞始まりで混在しているもの - **より自然な名詞句が明確に存在する**: `Fixing the height` ↔ `Fixed height` のように短く強い代替がある場合 - **語感が誤読を招く**: `Fixing X` はバグ修正と混同されうる | Before | After | 理由 | |--------|-------|------| | `### Switching between horizontal and vertical layouts at a breakpoint, with changing media aspect ratio` | `### Breakpoint-responsive horizontal/vertical layout` | 動名詞 + 関係節で長すぎる | | `### Changing the X and adding Y` | `### Custom X with Y` | 動名詞連結で冗長。代替の名詞句が短く強い | | `### Fixing the height` | `### Fixed height` | "Fixing" はバグ修正の意に取られる | | `### Specifying heading levels` | `### Heading levels` | より短い名詞句で十分 | | `## Benefits of X Management` | `## Why Use X?` | 名詞重畳→修辞疑問形 | | `## How to read the tables on this page` | `## Reading the Tables` | 冗長 | | `## Displays` / `## Positions` | `## Display` / `## Position` | CSSプロパティ名は単数 | | `## COLOR` / `## PALETTE` | `## Semantic Colors` / `## Palette Colors` | all-caps 見出しは英語docsで非標準。Title Case に統一 | 逆に、以下は通常そのまま維持してよい: - `### Using Next.js ` — MDN/Astro でも普通の形 - `### Adding icons and badges` — 短く明確な動名詞 + 目的語は問題なし - `### Customizing Semantic Colors` — `Customizing X` は React/Tailwind docs で一般的 ### 構文（受動態・冗長な前置きの解消） | Before | After | |--------|-------| | `This allows X to be rendered through Y.` | `This lets you render X through Y.` | | `X is provided as Y.` | `X is available as Y.` / `Lism provides X as Y.` | | `Here is an example of X using Y.` | `This example uses Y to X.` | | `The following are useful Xs that …` | `These Xs are useful for …` | | `By doing this, …` | `This way, …` / `As a result, …` | | `Consider the following configuration:` | `Here's an example configuration:` | | `You can do so as follows:` | （削除して直接コードブロックへ） | ### 単語選択・表記揺れ | Before | After | 補足 | |--------|-------|------| | `the as property` | `the as prop` | コンポーネントAPI 文脈では prop | | `slightly unique` | `slightly different` | unique は absolute（程度副詞と共起しない） | | `× （掛け算記号）`を散文中で | `–` (en-dash) または `and` | "every property × every breakpoint" → "every property–breakpoint combination" | | 短文2連 `X is Y. It is Z.` | 1文に統合 | 「〜です。〜です。」の直訳 | | カンマ＋句点 `## Zero-build, works in any environment.` | em-dash 構成 / 句点削除 | 見出しの混在不自然 | ## セルフチェックリスト（翻訳完了前に必ず確認） 各ファイルの翻訳・更新を終えた後、以下を順に確認してから報告すること： 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` — 差分なし ``` --- > Source: [lism-css/lism-css](https://github.com/lism-css/lism-css) — distributed by [TomeVault](https://tomevault.io).