vietnamese-tech-writing

ベトナム語のエンジニアリング文書とプロダクト文書（vi-VN）

ベトナム語の技術文書とマーケティング文書では、問題の起こり方が異なります。マーケティング文書は、直訳しすぎることで不自然になります。技術文書は、ベトナム語にしすぎることで不自然になります。つまり、ベトナム人エンジニアが英語のまま使う用語を翻訳し、システムを説明する文書で読み手に呼びかけてしまいます。

この2つの欠陥は、エンジニアではない校正者には見えませんが、文書を使わなければならないチームにはすぐにわかります。

ステップ 1 — 一言も書く前に、文書の種類を決める

文書の種類によって決まることが2つあり、どちらもランディングページでの標準的な選択とは逆になります。

書く文書	文体	用語
RFC、設計文書、ポストモーテム、ランブック、仕様書	非人称 — bạn は一切使わない	ベトナム語では形式的な表現に寄せる（bộ nhớ đệm、cơ sở dữ liệu）
README、チュートリアル、API ドキュメント、UI 文言、リリースノート	bạn	ユーザー向けの名詞はベトナム語にする
PR の説明、コードレビュー、スタンドアップ、チャット	mình／呼びかけなし	全体を通して英語の用語を使う
ステータスページ（顧客向け）	quý khách	平易で、技術的でない表現

RFC での bạn は欠陥です。 ベトナム語には自然な非人称表現があります。たとえば Hệ thống sẽ tự động retry や Cần cấu hình biến môi trường です。一方、英語にはそのような表現がないため、翻訳文には bạn が頻繁に使われます。

文書ごとの文体と、bạn の代わりに使う非人称表現については、references/doc-registers.md を参照してください。ほかのベトナム語スキルと共有する代名詞の一覧は、references/register-matrix.md を参照してください。

ステップ 2 — 基本ルール（必須。ファイルを移動する必要はありません）

1. 英語の用語は英語のままにします。 deploy、commit、merge、bug、server、cache、deadline、sprint、backlog、pull request。これらを翻訳することは、機械翻訳だと最もはっきりわかる特徴です。commit を cam kết と訳すのは最悪の例です。これは「誓約する」を意味する実在の単語です。
2. 環境名は絶対に翻訳しません。 production、staging、dev。triển khai đến sản xuất は、ベトナム人エンジニアが書いたことのある文ではありません。
3. 識別子、ブランチ名、コミットの件名は ASCII にします。 発音区別符号は一切使いません。コミットの本文はベトナム語でもかまいませんが、件名には使えません。
4. NFC の Unicode を出力します。 合成済みの ế（U+1EBF）を使います。NFD はフォントの表示を崩し、文字数をプラットフォームの上限以上に増やし、検索を妨げます。
5. ベトナム語には文法上の複数形がありません。 ICU メッセージでは other のみを使います。vi ファイルに one、few、many、zero の分岐があれば、必ず不具合です。=0 セレクターは問題ありません。
6. 文書ごとに声調記号の表記スタイルを1つ選びます — 既定では新式（hoà、thuỷ）です。どちらのスタイルも誤りではありませんが、混在させるのは誤りです。
7. 賛成・反対形式のアンケート尺度は絶対に使いません。 黙従バイアスにより、賛成の回答が約10ポイント増えます。対象となる特性そのものについて尋ねてください。
8. エラーには、何が起きたかと、次に何をすべきかを記載します。 開発者向けの画面では quý khách を絶対に使わず、ユーザーを責めないでください。

ステップ 3 — 用語を作る前に調べる

機械翻訳だとわかる翻訳調の表現のブロックリスト、英語とベトナム語の両方が現役で使われる用語（server／máy chủ、cache／bộ nhớ đệm — どちらかを選び、統一します）、およびユーザー向け UI 文言で定着しているベトナム語については、次を参照してください。

references/glossary.md — 機械可読形式のため、すべての行が lint ルールになります。

英語のままにする語の判断理由と、境界線上の用語を決めるフォーマルさの基準については、references/code-switching.md を参照してください。

ステップ 4 — i18n の落とし穴に対処する

ベトナム語のテキストは英語より25～30%長くなるため、幅が固定されたボタンではテキストが切れてしまいます。ダイアクリティカルマークがあると SMS は UCS-2 になり、1 セグメントの文字数が 160 文字から 70 文字に減ります。ユーザーはダイアクリティカルマークなしで検索するため、検索ではアクセント記号を区別しない一致が必要です。重ね書きのダイアクリティカルマーク（ề、ộ、ữ）を含まないフォントサブセットでは、表示が気づかれないまま崩れます。

references/i18n-hazards.md — 数字、日付、通貨については references/locale-formatting.md、NFC、照合、入力方式については references/unicode-and-tone.md も参照してください。

スターターリソースファイル：assets/messages.vi.json.template — ASCII のキー、NFC の値、other のみの複数形、両方の敬語レベルを含みます。

ステップ 5 — プロダクトとリサーチに関する文章

リリースノートは、ユーザーが得られるメリットを先に示し、過去形で記述します（Đã sửa lỗi…、Đã thêm…）。アジャイル用語は英語のままにします（sprint、backlog、roadmap。lộ trình も使用できます）。ユーザーストーリーは Là [vai trò], tôi muốn… とし、Như một [vai trò] は使いません。

アンケートは、このスキルが真価を発揮する場面です。ベトナム語のアンケートは、表現が悪くても一見問題なく読めてしまい、誤った数値を返すことがあるためです：references/survey-design.md。

ステップ 6 — 主張を確認する

アプリストアの掲載文やアプリ内の主張は、Luật Quảng cáo 16/2012/QH13 における広告にあたります。サブタイトルに根拠のない tốt nhất や số 1 を含めると、キャッチコピーではなく規制対象の主張になります。

ジャンル固有の一覧は references/banned-phrases.md、あらゆるベトナム語スキルで共通する広告、同意、個人データに関するルールは references/compliance.md を参照してください。

ステップ 7 — 検証し、修正してからリリースする

文章を書いたら、すぐにバリデーターを実行してください。エラーが報告された場合は修正し、再度実行してください。合格してからのみ、文章を提出してください。 NFC 違反や ICU の複数形の不具合は、読んだだけでは気づけません。

python scripts/validate_copy.py path/to/doc.md --register eng-impersonal
python scripts/validate_copy.py .git/COMMIT_EDITMSG --doctype commit
python scripts/validate_copy.py messages/vi.json --doctype identifier
python scripts/validate_copy.py survey.md --doctype survey

• --register eng-impersonal|eng-readme|saas|re|formal|consult|... を指定すると PRO002 が有効になります。 --list-rules を実行すると、このスキルが出力するすべてのルールが表示されます。
• 構造に関するルールを有効にするのは --doctype です。 これを指定しない場合、構造ルールは無効のままです。30 文字制限はアプリストアのサブタイトルには適切でも、設計ドキュメントにはまったく適さないためです： commit、branch、identifier、rfc、postmortem、runbook、survey、 app-store-title、app-store-subtitle、app-store-short-description、consent。
• 終了コード 0 = エラーなし、または警告のみ。終了コード 1 = 修正が必要なエラーあり。
• 機械可読な検出結果には --json を、警告も含めて失敗扱いにするには --strict を指定します。
• --fix は NFC 違反をその場で書き換えます。それ以外のルールは、人による判断が必要です。

特定のウェブフォントが指定されている場合は、グリフの対応状況を確認します：

python scripts/check_font_coverage.py path/to/copy.md

ステップ 8 — 作業例を読み、最後に人の確認を受ける

長文を書く前に、悪い例から良い例へのコーパスを読んでください。各ペアには修正する失敗パターンが記載されており、その診断は個々の文字列にとどまらず応用できます。

references/examples.md

次に、チェックリストを実行してください。リンターはエンコーディング、禁止された直訳表現、doctype によって有効になる構造ルールを検出します。しかし、英語の用語を新たにベトナム語にした表現が自然か、アンケートの設問が誘導的でないか、エラーメッセージが実際に行動につながる内容かどうかは判断できません。こうした点は、ソフトウェアのリリース経験があるネイティブスピーカーによる確認が必要です： references/qa-checklist.md