CLAUDE.md

1# Hiddify App — Claude project instructions
2 
3## Localization / translations (slang)
4 
5The app uses **slang** (v4.8.1) for i18n — a type-safe framework that turns the JSON translation files into Dart code, with tooling for analysis, applying translations, and structural key edits. Config is in `build.yaml` under `slang_build_runner`.
6 
7**Official docs: https://pub.dev/packages/slang** — read them whenever you need slang's syntax or features (plurals, context, linked translations, modifiers, interpolation). Learn the framework's rules yourself; they are not repeated here.
8 
9Project setup:
10- Base locale: `en`. Sources: `assets/translations/<locale>.i18n.json`.
11- Locales (11): `en` (base) + `ar`, `es`, `fa`, `fr`, `id`, `pt-BR`, `ru`, `tr`, `zh-CN`, `zh-TW`.
12- Generated code (`lib/gen/translations*.g.dart`) and the analyze reports (`_missing_translations*.json`, `_unused_translations*.json`) are **git-ignored** — never committed, no cleanup needed.
13- `fallback_strategy: base_locale` → a missing secondary string shows English at runtime.
14- Namespaces are off → plain key paths, e.g. `t.profile.add.title`.
15 
16### Essential commands
17 
18- `dart run slang` — generate the Dart code from the JSON. Run after **any** JSON change so the app compiles.
19- `dart run slang analyze [--split] [--full]` — compare every locale against `en`. Writes `_missing_translations*.json` (in `en`, missing elsewhere) and `_unused_translations*.json` (in a locale, not in `en`) into `assets/translations/`. `--split` = one file per locale; `--full` = also flag `en` keys unused in `lib/` source.
20- `dart run slang apply [--locale=fa]` — write the **translated** `_missing_translations*.json` back into each locale file (keeps `en`'s key order).
21 
22slang also has `edit add/delete/move/copy`, `clean`, `normalize`, `outdated`, and `stats` — use these (see docs) for structural edits instead of hand-editing every locale.
23 
24### Translation principles (priority order)
25 
261. **Material Design 3 (top priority):** sentence case, concise, no trailing period on short UI strings, action-oriented.
272. **Context-based:** Hiddify is a **v2ray / VPN client**. Keep technical terms in **English** — VPN, proxy, DNS, TUN, WARP, Psiphon, VLESS, VMess, Trojan, Shadowsocks, Reality, XTLS, sing-box, inbound / outbound, TLS, ping, etc.
283. **Preserve non-text exactly:** placeholders (`$name`, `${host}`), links, plural / context blocks, modifiers. Translate values only, never keys. Keep valid JSON.
29 
30### During development — English only
31 
32- Edit **only** `assets/translations/en.i18n.json` — text and JSON structure.
33- Leave the other 10 locales untouched (fallback shows English). This saves tokens and time.
34- For **important or long** strings, propose the English wording and **wait for my approval**.
35- To rename / move / delete an existing key, run `dart run slang edit move|delete <path>` (token-free, keeps existing translations).
36- Run `dart run slang` after editing so the app compiles.
37 
38### Committing translation edits
39 
40This applies to **any commit that contains translation edits** — not every commit. A code-only change is committed normally. Translation edits go in their own commit(s), never mixed with code, for a clean translation history:
41 
421. **English / source — on its own, first.** Stage and commit **only** `assets/translations/en.i18n.json`. During development you edit only `en`, so at commit time it is normally the only changed translation file — that is why English comes first.
432. **Other 10 locales — together, afterwards.** When you translate them: `dart run slang analyze --split` → translate the missing strings (principles above) → `dart run slang apply` → `dart run slang` → stage all the other `assets/translations/*.i18n.json` files and commit them in one commit.
44 
45### Final check (after both commits)
46 
47`dart run slang analyze --full` → both reports should hold no locale entries (only the `@@info` header): nothing missing, nothing extra. If something shows up, tell me and fix it in a follow-up.
48