# Translating FolderView Plus

FolderView Plus uses English as its source catalog and falls back to English whenever a translation is missing. A locale is presented as complete after every current source message is translated, the automated language contracts pass, and the project maintainer accepts it for shipping. Native-speaker feedback remains welcome, but it is not required to ship or retain a complete catalog.

## Catalog layout

- `src/folderview.plus/usr/local/emhttp/plugins/folderview.plus/langs/en.json` contains legacy messages.
- `src/folderview.plus/usr/local/emhttp/plugins/folderview.plus/langs/namespaces/en/` contains feature-oriented modern messages.
- `src/folderview.plus/usr/local/emhttp/plugins/folderview.plus/langs/<locale>.json` contains existing non-English legacy translations.
- Modern translation scaffolds live under `langs/namespaces/<locale>/<namespace>.json`; add reviewed messages to the existing locale file instead of copying English into it.
- `legacy-surface.json` is generated from remaining static and runtime-written legacy UI text. Do not edit its hashed keys by hand; regenerate it with the repository builder.
- `langs/registry.php` records the native language name, direction, and review status used by the runtime loader.

Message keys describe meaning instead of copying English wording. New keys should use a feature namespace, for example `docker.privacy.mask-lan-ips` or `wizard.navigation.review`. Do not rename a key solely because the English sentence was edited.

`scripts/build_i18n_surface_catalogs.mjs --translate` also fills missing explicit namespace keys from the English catalog and validates parameter placeholders. This keeps new Dashboard and diagnostics messages aligned across supported locales while preserving existing translations.

## Translation status

- `source`: authoritative English source.
- `complete`: every current source message is translated, structurally validated, and maintainer accepted for shipping.
- `partial`: useful translations exist, but English fallback remains visible for missing or stale messages.
- `placeholder`: no reviewed translation is currently shipped. The runtime deliberately loads English instead of an English-copy locale file.

Do not fill untranslated keys with copied English text to increase the apparent completion percentage. Missing keys are the correct representation of unfinished work.

## Message rules

1. Preserve parameters such as `$1` and `$2` exactly.
2. Keep supported markup and links equivalent to the English source. Never add scripts, event attributes, or untrusted URLs.
3. Translate full sentences instead of joining independently translated fragments.
4. Use `{{PLURAL:$1|singular|plural}}` where the sentence depends on a count. Languages may provide every plural form supported by jquery.i18n.
5. Keep product names such as FolderView Plus, Unraid, Docker, and User Scripts unchanged unless an established localized name exists.
6. Preserve the distinction between Docker containers, virtual machines, folders, members, rules, previews, and backups.

## Glossary

| English term | Meaning in FolderView Plus |
|---|---|
| Folder | A visual organization group; not a filesystem directory. |
| Member | A Docker container, VM, or child folder assigned to a folder. |
| Rule | An automatic assignment condition evaluated by FolderView Plus. |
| Preview | The compact member display shown inside or alongside a folder row. |
| Runtime page | The Unraid Docker, VM, or Dashboard page enhanced by the plugin. |
| Snapshot | A saved FolderView Plus configuration used for compare or recovery. |
| Import | Applying a FolderView/FolderView Plus configuration export. |

## Validation

Run these repository-provided checks before submitting a translation:

```bash
bash scripts/i18n_guard.sh
bash scripts/lang_usage_guard.sh
```

The guards validate catalog JSON, metadata, duplicate keys, message parameters, plural syntax, HTML consistency, source-code references, unused keys, and zero uncovered user-facing UI strings.

When English legacy UI text changes, regenerate the complete surface catalogs before running the guards:

```bash
node scripts/build_i18n_surface_catalogs.mjs --translate
```

The generator preserves existing translations, translates only new or changed surface messages, protects numbered parameters, updates catalog metadata, and writes the extraction report. Translation is a repository maintenance step; installed plugins never contact a translation service.

## Pseudo-locales

After a FolderView Plus page has loaded, use the browser console to test text expansion:

```js
FolderViewPlusI18n.usePseudoLocale('en-XA')
```

Use the bidirectional pseudo-locale to test right-to-left layout:

```js
FolderViewPlusI18n.usePseudoLocale('ar-XB')
```

Restore the Unraid-selected locale with:

```js
FolderViewPlusI18n.restoreLocale()
```

Test Docker, VMs, Dashboard, Settings Basic and Advanced, the Setup Assistant, import dialogs, diagnostics, and the modern folder editor. Look for clipping, fixed-width controls, incorrect icon placement, English strings, and broken keyboard or screen-reader labels.

The repository browser smoke run also activates `en-XA` and `ar-XB`, verifies language and direction state, and saves full-page screenshots for expansion and RTL review.

## Regional locales

Locale names follow BCP 47. Unraid underscore identifiers are normalized before resolution; for example, `zh_CN` becomes requested locale `zh-CN` and resolves to the canonical `zh-Hans` catalog. Add a regional file only when the language actually differs, such as `pt-BR`, `pt-PT`, `zh-Hans`, or `zh-Hant`. The browser runtime activates the resolved catalog while preserving the requested locale on the document and in diagnostics.

FolderView Plus distinguishes `pt-BR`, `pt-PT`, `zh-Hans`, and `zh-Hant`. Generic Chinese plus Mainland China, Singapore, and Malaysia variants resolve to `zh-Hans`; Taiwan, Hong Kong, Macau, and explicit Traditional Chinese requests resolve to the independently translated `zh-Hant` catalog. Unraid `no_NO` resolves to canonical Norwegian Bokmål `nb`, while both Unraid `bn_BN` and standard `bn_BD` requests resolve to canonical Bengali `bn`.

The Traditional Chinese maintenance path uses independent `zh-TW` translation followed by one pinned `opencc-s2twp-1.4.1` Taiwan normalization pass. The root catalog records that profile so repeated builds cannot reconvert already reviewed text. OpenCC is a development-only dependency and is never included in or executed by the installed Unraid plugin.

The shipped Arabic catalog is right-to-left. Changes to shared UI layout must continue to pass both the production `ar` browser fixture and the synthetic `ar-XB` stress fixture; do not assume pseudo-localization alone proves that mixed Arabic text, container names, paths, ports, and version strings render correctly.

## Review workflow

1. Update the English source and increment the catalog version.
2. Run the guards and review newly missing translations.
3. Translate with UI context or screenshots available.
4. Machine-assisted translation may be used, but preserve product terms, parameters, markup, and locale-specific plural forms.
5. Run the structural guards and review high-risk wording such as destructive actions, imports, restores, and deletion choices before maintainer acceptance.
6. Update locale metadata and registry status only after every source key is present and the catalog is accepted for shipping.

The repository is prepared for a Weblate project using the component masks and review controls in [TRANSLATION_PLATFORM.md](TRANSLATION_PLATFORM.md). JSON pull requests remain supported so the project is not dependent on an external translation service.

## Coverage and extraction

Diagnostics reports legacy and modern namespace coverage separately, whether a locale was reviewed against the current English source, and the count of translations that may be stale. The generated `legacy-surface` namespace binds remaining initial and dynamically inserted UI text at runtime. `langs/extraction-report.json` must report zero uncovered candidates, and the guards fail whenever source UI and the generated namespace drift apart.