Documentation Translation Guidelines

We welcome community contributions to help translate the Fish documentation into any language. This guide outlines the workflow, disclosure policies, relaxed contributor rules, and best practices for translating documentation.

---

Scope

Translation applies exclusively to documentation (markdown files under docs/ and project guides).

• Source code, tests, identifiers, and commit messages must remain 100% in English.
• CLI commands, flag names, code snippets, and configuration keys inside the documentation must not be translated.

---

Relaxed Rules for Documentation Contributors

To make contributing as welcoming and straightforward as possible, the following relaxed policies apply to documentation:

1. Incremental / Partial Translations Are Welcome:

   • You do not need to translate an entire document in one go.
   • Translating a single section (such as Installation or Quick Start) is completely acceptable.
   • For uncompleted sections, you may keep the original English text or leave an HTML comment like <!-- TODO: translate this section -->.

2. No Local Rust Setup Required:

   • You do not need to clone the repository or install Rust locally to contribute to docs.
   • You can edit markdown files directly through the GitHub Web UI by clicking the pencil icon on any file.

3. Fast-Track Review:

   • Pull requests for typo corrections, formatting improvements, link updates, and translation refinements are fast-tracked and merged promptly.

---

Supported Languages

Translations are accepted for all languages. Fish maintains 5 core prioritized languages alongside open contributions for any additional language:

Language	Code	Status	Role
English	en	Active	Canonical Source of Truth
Simplified Chinese (简体中文)	zh-CN	Open	Core Community Language
Traditional Chinese (繁體中文)	zh-TW	Open	Core Community Language
Japanese (日本語)	ja	Open	Core Community Language
Vietnamese (Tiếng Việt)	vi	Open	Core Community Language
All Other Languages (Spanish, French, German, Korean, etc.)	*	Open	Community Languages

---

Tooling Policy & Mandatory Machine Translation Disclosure

1. Automated & AI Translation Tools Are Permitted

Contributors may use AI assistants (ChatGPT, Claude, Gemini) and machine translation engines (DeepL, Google Translate) to draft or accelerate translations.

2. Mandatory Machine Translation Disclosure

Transparency is required for all submitted translations. When submitting a translation, you must disclose in your Pull Request description whether automated tools were used.

Please select the appropriate tier in your PR:

• Tier 1 - Manual Native Translation: 100% human-translated by a native or fluent speaker.
• Tier 2 - AI / Machine-Assisted with Native Review: Initial draft generated with AI/machine translation, thoroughly reviewed and corrected by a native or fluent speaker.
• Tier 3 - Automated / AI Draft (Needs Review): Generated by an AI/machine translation tool, pending in-depth review by a native speaker from the community.

3. Native Speaker Priority

Translations that have been reviewed or authored by native/fluent speakers take priority for merging to ensure natural phrasing and precise technical accuracy.

---

Directory Structure

Translations are organized in language subdirectories under docs/ using standard ISO language codes:

docs/
├── getting-started.md       # English (Canonical Source)
├── architecture.md          # English (Canonical Source)
├── vi/                      # Vietnamese
│   ├── getting-started.md
│   └── architecture.md
├── zh-CN/                   # Simplified Chinese
│   ├── getting-started.md
│   └── architecture.md
├── zh-TW/                   # Traditional Chinese
│   ├── getting-started.md
│   └── architecture.md
├── ja/                      # Japanese
│   ├── getting-started.md
│   └── architecture.md
└── <lang-code>/             # Any other language (e.g., es, fr, de, ko)
    └── getting-started.md

---

How to Submit a Translation

Option A: Via GitHub Web Interface (Easiest)

1. Navigate to the file under docs/ on GitHub.
2. Click the Edit this file (pencil) icon.
3. Save your changes into a new branch and open a Pull Request.

Option B: Via Git Command Line

1. Create a branch from dev:

   git checkout -b docs/translate-<language>-<topic>

2. Translate the document:

   • Copy the English file from docs/<file>.md to docs/<lang-code>/<file>.md.
   • Translate the text while keeping markdown syntax, file links, and code blocks intact.

3. Disclose translation method in your PR description:

   ### Translation Disclosure
   - [ ] 100% Manual Translation (Native/Fluent speaker)
   - [x] AI/Machine-Assisted with Native Review (Tool used: DeepL / Claude / Google Translate)
   - [ ] Automated Draft (Needs Community Native Review) (Tool used: ...)

4. Submit a Pull Request targeting the dev branch.

Option C: Via Automated Translation Tool

Run the built-in syntax-aware translator to automatically update or translate documentation into the 4 target languages (vi, zh-hans, zh-hant, ja):

npm run docs:translate
# Or check translation synchronization:
npm run docs:translate:check