# Internationalization (i18n)
This documentation site is built with Sphinx. Multi-language support uses Sphinx gettext catalogs (`.po` files).
## Current setup
- Default language: English (`en`) at site root
- Chinese (Simplified): `zh_CN` published under `/zh/`
- Translation files live in `code/docs/locale/<lang>/LC_MESSAGES/`
GitHub Pages builds both languages in `code/.github/workflows/pages.yml`.
This site also includes a global language switcher (top-right on every page) implemented via Sphinx template overrides under `code/docs/_templates/`.
## First-principles translation guidelines (for consistency)
To keep the Chinese site **elegant, coherent, and context-consistent**, treat translation as a *semantic mapping* rather than a word-for-word rewrite:
- **Preserve meaning first**: keep definitions, constraints, and caveats intact; avoid “free” paraphrasing that changes technical intent.
- **Keep structure stable**: don’t reorder sections or rewrite headings into new concepts; mirroring the English information architecture keeps navigation and cross-page references consistent.
- **Translate user-facing text, not code**: do *not* translate tool names, parameter names, file paths, environment variables, or code blocks.
- **Be consistent with terminology**: pick one Chinese term per core concept and reuse it everywhere; add new terms intentionally (not ad hoc).
- **Prefer clarity over literalness**: when English is terse, use natural Chinese but keep it concise.
### Recommended terminology (zh_CN)
| English | zh_CN |
|---|---|
| spatial transcriptomics | 空间转录组 |
| spatial domain(s) | 空间区域 |
| deconvolution | 去卷积 |
| cell type annotation | 细胞类型注释 |
| spot | spot（必要时首次可写“spot（点位）”） |
| ligand–receptor (LR) | 配体-受体（LR） |
| trajectory / pseudotime | 轨迹 / 伪时间 |
| workflow | 工作流 |
## Add a new language
1) Create a locale folder:
```
code/docs/locale/<lang>/LC_MESSAGES/
```
Example: `code/docs/locale/ja/LC_MESSAGES/` for Japanese.
2) Generate/update translation templates (`.pot`):
```
cd code/docs
sphinx-build -b gettext -d _build/doctrees/gettext . _build/gettext
```
3) Create/update `.po` files (recommended: `sphinx-intl`):
```
cd code/docs
sphinx-intl update -p _build/gettext -l <lang>
```
4) Translate strings in:
```
code/docs/locale/<lang>/LC_MESSAGES/*.po
```
5) Build that language locally:
```
cd code/docs
sphinx-build -b html -d _build/doctrees/<lang> -D language=<lang> . _build/html/<lang>/
```
## Notes / pitfalls
- Keep filenames the same across languages; Sphinx switches text via catalogs, not via separate source trees.
- Raw HTML blocks (``.. raw:: html``) are not extracted for translation. Prefer normal reStructuredText/Markdown text for translatable UI copy.
- Avoid translating code blocks unless you *really* want localized code comments/output.
## Quality checklist (recommended)
- `msgfmt -c` on updated `.po` files (catches format mistakes early).
- Build the Chinese site locally and spot-check:
- Navigation labels (sidebar, section titles)
- Tables and admonitions
- Cross-page links (especially `/zh/...`)
