# PicViewer Internationalization Conventions

Task scope and document precedence are defined in [AGENTS.md](../AGENTS.md).

## Goals

- Initially support `zh_CN` and `en`.
- Use `.ts/.qm + QTranslator`.
- Runtime language switching is not supported; the language is determined at startup.

## Language Selection Rules

Priority is as follows:

1. Environment variable `PICVIEWER_LANG`
2. System language `QLocale.system().name()`
3. Default `en`

Supported mappings:

- `zh` / `zh_CN` / `zh-CN` -> `zh_CN`
- `en` / `en_US` / `en-GB` -> `en`
- Other values -> treated as unset

## Text Extraction and Translation Files

- Translation source directory: `src/pic_viewer/ui/resources/i18n`
- Translation files:
  - `picviewer_zh_CN.ts`
  - `picviewer_en.ts`
- The Qt source language is English; `picviewer_zh_CN.ts` provides Chinese translations, and `picviewer_en.ts` keeps the same English text as the source.

Run the commands below from the repository root after activating `PicViewer` in the same shell.

Update TS:

```bash
python scripts/i18n/update_ts.py
```

`update_ts.py` uses the built-in Python extractor by default. If a local PySide6
`lupdate` wrapper is available and should be used explicitly, pass it with
`--lupdate`.

Generate QM:

```bash
python scripts/i18n/build_qm.py
```

## Repository and Release Conventions

- Only `.ts` files are committed to the repository.
- CI/packaging generates `.qm` files and includes them in the release artifacts.
- If no Chinese `.qm` is available when running locally from source, the application automatically falls back to English and does not block development.

## User-Visible Text Changes

- Read this document whenever user-visible text is added, changed, or removed, regardless of the source layer.
  This includes Controller-localized backend messages, menus, labels, tooltips, accessible text, dialogs, and status text.
- Update the TS sources with `python scripts/i18n/update_ts.py` and inspect both English and Chinese files for missing
  or outdated entries, translations, and placeholders. For deletions, inspect obsolete entries as well.
- Layout or style changes with unchanged copy do not require translation extraction or TS edits. Check translated
  text fit when geometry changes using [the visual checks](visual-testing.md).
- All user-visible text must go through translation functions and must not be hardcoded directly in UI display paths.
- The UI layer uniformly uses `_tr(...)`.
- The service layer and domain layer must remain free of Qt dependencies; fixed prompt text from the backend is mapped to localized text in the Controller layer.

## Pre-Release Checks

1. Run `python scripts/i18n/update_ts.py` and confirm that no text is missing.
2. Run `python scripts/i18n/build_qm.py` and confirm that `picviewer_zh_CN.qm` and `picviewer_en.qm` can be generated.
3. Start with `PICVIEWER_LANG=en` to verify the English source text; start with `PICVIEWER_LANG=zh_CN` to verify that menus, labels, dialogs, the status bar, and metadata empty states are all in Chinese.