fullseye

Fullseye の多言語対応 — 全体設計 / Internationalisation design

言語ごとの文言はすべてテーブル(JSON)に一元化し、コード変更なしで追加・上書き できる。レイヤは 5 つで、それぞれ役割と機構が違う。 All translations live in JSON tables; five layers with distinct mechanisms.

対象言語(2026-09-05 決定)

ja en zh(简体) tw(繁體/台湾) ko de の 6 言語。半導体サプライチェーンの 主要国を見て選んだ —— 日本・米英・中国・台湾・韓国・ドイツ。

★ 台湾向け繁体字のコードは、ファイル名を 2 文字にそろえるため tw としている。 標準タグ(BCP 47)では zh-TW / zh-Hant であり、tw は本来 ISO 639-1 で Twi 語の 記号なので、OS・ブラウザから来るロケールは必ず tools/opdocs.py の normalize_lang()(対応表 LANG_ALIASES)を通してから使うこと。

レイヤ	ベース言語	テーブル	切替
① Studio UI(メニュー/ボタン/ツールチップ/ガイド)	英語	studio_assets/i18n.json(strings / tooltips / guide)	Tools ▸ Language(記憶される)
② ライブラリのメッセージ(例外/CLI)	英語(traceback・ログ・検索の通貨)	fullseye/i18n/<lang>.json + ユーザーの FULLSEYE_I18N_DIR(後者優先)	env FULLSEYE_LANG / fsi18n.set_language()
③ op ヘルプの枠(見出し・ラベル・入力契約)	日本語(生成器の原文)	docs/i18n/opdocs.json + docs/i18n/op_summary.json	ヘルプ冒頭の言語リンク / UI 言語に追従
④ コメント・docstring・op 本文	日本語	併記は ja+en まで(zh 以降は ⑤ の方式)	—
⑤ 散文ドキュメント(記事・ガイド・カタログ)	日本語	兄弟ファイル <name>.<lang>.md	ファイルを開く

① Studio UI

• 対訳テーブルは studio_assets/i18n.json の一箇所。strings(ラベル対訳、英語原文が キー)・tooltips・guide。言語追加は languages に 1 行 — コード変更なし。
• 未訳の文字列は英語のまま表示(graceful fallback)。
• ★2026-09-05 に塞いだ穴が 2 つ: (a) strings 44 件は ja しか入っておらず、 中文を選んでもメニューは英語のままだった。(b) apply_language に ("en","ja","zh") という固定の許可リストがあり、languages に足した言語は メニューに出るのに選ぶと英語へ戻った(「表に足せば増える」という約束をコード 側が破っていた)。いまは LANGUAGES に載っているものを受け付け、 tests/test_opdocs.py が両方を検査する。
• 実装: tr() + スナップショット registry(win._label_en / win._tt_en)。詳細は docs/STUDIO_GUIDE.md の「多言語対応」節。

② ライブラリのメッセージ(fsi18n)

例外メッセージは英語がベース(2026-08-30 に日本語のみだった 336 箇所を英語へ統一)。 その上で、切替の下地として fsi18n を用意している:

from fsi18n import msg
raise ValueError(msg("points must be (N, 3) (got shape {shape})", shape=P.shape))

• テンプレートを翻訳してから format する(値が埋まった後では照合できない)。
• 言語選択: FULLSEYE_LANG=ja(env)または fsi18n.set_language("ja")。既定 en は テーブルを読まない素通し=ゼロコスト。
• 翻訳テーブルはユーザーが作れる(設計要件): FULLSEYE_I18N_DIR の指す ディレクトリに <lang>.json(英語テンプレート → 訳)を置くと、同梱テーブル (fullseye/i18n/<lang>.json)より優先される。新しい言語もファイルを置くだけ。 プログラムからは fsi18n.register(lang, mapping)。
• 訳が無い・訳が壊れている場合は英語へフォールバックし、msg() 自体は決して例外を 出さない(メッセージ機構がエラー源になってはいけない)。
• Studio の Python Editor は実行サブプロセスに FULLSEYE_LANG(UI の言語)を伝播する。
• 採用は漸進(honest): 既存の raise は英語直書きのまま。fsi18n.msg() 経由への 置換は新規コード・主要バリデータから進める(規約は CONTRIBUTING.md)。

③ op ヘルプの枠(生成器の対訳 — 0.1.7)

op ヘルプ(studio_assets/op_help/**)は docs/ops/** の Markdown から生成される。 生成物を直接訳しても次の再生成で消えるので、生成の入力側を訳す。

• 枠の対訳表 docs/i18n/opdocs.json —— キーは原文(日本語)そのもの。 studio.py の tr() と同じ規約で、翻訳者はキーを発明しなくてよく、原文を書き換えれば その行は自動的に「未訳」に落ちる(古い訳が黙って残らない)。言語追加は各行に 1 列。 未訳は原文のまま出て、tools/opdocs.py html が stderr に件数を出す。
• op 要約の対訳表 docs/i18n/op_summary.json —— キーは <dim>/<op>、fp は 原文の指紋。指紋が合わない訳は出さない(日本語と「未訳」の断り書きに戻る)。
• 生成: tools/opdocs.py html が <op>.html(日本語)に加えて <op>.<lang>.html を 5 言語ぶん書く。ガイド(人が書いた散文)は日本語 1 枚のままで、 各言語版には日本語のみである旨の 1 行だけを冠する。
• 導線: ヘルプ冒頭に実在する言語だけを並べた切替リンク(lang:<code>)。UI の 言語を切り替えるとヘルプもそれに追従する。
• ★訳したふりをしない。枠と要約が訳されていて本文が原文のままのときは 「以下の詳細説明は原文のままです」、要約すら無いときは「まだ訳がありません」と、 どこまで訳したかを頁自身が言う。判定は表を引けたかではなく 読み手の言語で書かれているか(not_in_language())で行う。
• ★ja も翻訳先。原文が英語の要約が 521 本あり(0.1.7 で分母を 935 → 1,722 に増やした時点の実測。当初は 349 本)、日本語のヘルプを開いても英語の ままだった。全部に日本語訳を入れて ja 1,722/1,722。訳がある op だけ <op>.ja.html を生やす (原文が日本語の op にノートと同じ中身の兄弟を並べても情報は増えない)。 docs/ops/** のノートは docstring の写しなので触らない。

④ コメント・docstring(併記は ja+en まで)

• 新規・改訂コードのコメント/docstring は日本語と英語の併記を推奨 (模範例: fsi18n.py)。既存コードは触るタイミングで併記化。
• op ノート(docs/ops)は docstring から自動生成されるため、docstring の二言語化が そのまま英語版ノート/help の自動生成につながる(将来ウェーブ)。
• ★併記は 2 言語(ja+en)が上限(2026-09-05 決定)。三言語を 1 つの docstring に 詰めると読めなくなり、コードの可読性のほうが先に壊れる。中国語以降は ④ の 兄弟ファイル方式に寄せる —— 散文は散文として訳し、コードには持ち込まない。

対象外(honest)

• 研究スクリプト(vloop* / fullseye_3dgs / janken* 等、非出荷)は日本語のまま。
• worked examples の教材文(assert メッセージ・print)は現状日本語(④ とセットで 将来対応)。

⑤ 散文ドキュメントの対訳(兄弟ファイル方式)

対訳は原文の横に置く: <name>.md → <name>.en.md / <name>.zh.md。 docs/articles/exhibits/ で既にこの形が動いている(museum.ja.md / museum.en.md)。 新しい規約を増やさず、置き場所を見れば対応が分かるのが利点。

• 各ファイルの冒頭に言語スイッチャの 1 行を置く (> **言語 / Language**: 日本語 · English · 中文)。これが読者側の導線。
• README は PyPI の long description を兼ねるので、リンクは絶対 URLにする (リポジトリ相対パスは PyPI で壊れる)。表の中でパスだけ示す場合はバッククォートで 囲み、リンクにしない。
• 生成物(docs/ops/** の op ノート)はファイルを訳さない。生成の入力側 (見出し等の固定文字列 + op 要約の対訳表)を訳す方式に寄せる —— 生成物を直接 上書きしても次の再生成で消えるため。

★2026-09-06: ドキュメント索引を 6 言語にした(この方式の最初の本番適用)

docs/README.md(= GitHub Pages のトップ。独自ドメイン https://furuse.work/ で 配信されている)に、README.en.md / .zh.md / .tw.md / .ko.md / .de.md の 兄弟ファイルを揃えた。入口だけが日本語のままだったのが動機 —— op ヘルプは 既に 6 言語で出ていたのに、そこへ辿り着く索引が訳されていなかった。

決めたこと 3 つ:

• 言語スイッチャの行は訳さない。 どのページでも同じ 1 行で、各言語名は その言語で書く([日本語] · [English] · [简体中文] · [繁體中文] · [한국어] · [Deutsch])。読み手は自分の言語の綴りだけを探せばよい。
• リンク先は 6 言語すべて同じ(個別ドキュメントはまだ日本語のみ)。ただし 黙って日本語のページへ送らない —— 各言語版の冒頭に「訳されているのはこの 索引だけで、リンク先は当面日本語のみ」をその言語で 1 行書く。
• 繁體(tw)は简体(zh)の字を変えたものにしない。 台湾で通る語彙を使う (軟體 / 程式碼 / 專案 / 函式庫 / 影像 / 搜尋 / 匯出 / 涵蓋率 / 演算法)。 ここを機械変換で済ませると「訳したふり」になる。

訳し落としの検出は機械で数える: 見出し数(^#)と表の行数が 6 ファイルで 一致すること、](*.md) のリンク先が実在すること、README.??.md にかな・ カタカナが残っていないこと(言語スイッチャの 日本語 だけは例外)。 2026-09-06 の実測は見出し 8 / 表 25 行が 6 言語すべて一致、リンク切れ 0、 かな残り 0。

導線(どこから対訳に辿り着くか)

入口	見えるもの
PyPI プロジェクトページ	README.md(英語)。冒頭に総合紹介 en/ja へのリンク
GitHub リポジトリ前面	同上(同じ README)
README.md の Documentation map	総合紹介 en/ja、docs/articles/exhibits/
docs/articles/README.md	記事ハブ。ファイルと言語の対応表
各記事の冒頭	言語スイッチャ 1 行
Studio	Tools ▸ Language(ja/en/zh/tw/ko/de)
Studio の op ヘルプ	頁の冒頭に言語リンク(その頁に実在する言語だけ)

v1.0.0 までの計画(実測した分量)

対象	原文の分量	状態
Studio UI(strings 44 + tooltips 36 + guide)	2,870 字	6 言語 済(0.1.7)
op ヘルプの枠(見出し・ラベル・入力契約 40 件)	3,000 字	6 言語 済(0.1.7)
README.md(= PyPI 本文)	11,881 字	英語のみ
総合紹介記事	ja 244,200 / en 390,197 字	ja + en
op 要約(1,722 本 = 全 op)	実測	6 言語すべて 1,722/1,722 済(0.1.8)
op の説明が無い op	—	0 本(0.1.7 で 787 → 0。分母が 935 → 1,722 になった)
docs/OP_CATALOG.md(全 op の要約)	24,041 字	未
知識ガイド 12 本	24,000 字	未
族ガイド 26 本	91,889 字	任意
op docstring 本文(1,722 本)	54 万字超	対象外

v1.0.0 のゲート = op 要約 + OP_CATALOG + 知識ガイド(言語は需要順に足す。表に 1 列足すだけで増える形になっている)。op docstring 本文 54 万字は対象外 —— 量が 桁違いで、機械翻訳で撒くと技術的に間違った主張を 6 言語に複製することになる。 README に対象外であることを明記する。

honest: 機械翻訳で量を撒かない。この repo の実測では、翻訳を撒いても読まれない (閲覧は伸びるがストックが付かない)。訳すのは判断が移る文書に絞る。

This site is open source. Improve this page.