iiEsaywebUIapp/docs/localization.md

# Localization Guidelines

This app uses Flutter's gen-l10n with ARB files in `lib/l10n`.

- Source language: `en` (`lib/l10n/app_en.arb`)
- Translations: `lib/l10n/app_<lang>.arb` (e.g., `app_de.arb`)
- Generated Dart: `lib/l10n/app_localizations*.dart` (generated by Flutter)

## Adding New Strings

1. Edit `lib/l10n/app_en.arb` and add a key with a clear description meta entry.
   - Example:
   ```json
   "greeting": "Hello, {name}!",
   "@greeting": {
     "description": "Friendly greeting with user name.",
     "placeholders": { "name": { "type": "String", "example": "Alex" } }
   }
   ```
2. Run `flutter gen-l10n` or just `flutter run` to regenerate localizations.
3. Use it in code: `AppLocalizations.of(context)!.greeting(name)`.

## Placeholders and ICU

- Always declare placeholders under the `@key.placeholders` block with `type` and optional `example`.
- Use ICU for plurals/select:
  ```json
  "itemsCount": "{count, plural, =0{No items} one{1 item} other{{count} items}}",
  "@itemsCount": { "placeholders": { "count": { "type": "int" } } }
  ```

## Punctuation and Style

- Prefer typographic ellipsis `…` over `...`.
- Keep capitalization consistent across locales.
- Avoid embedding brand names in placeholders; keep them literal in strings.

## Weblate

This repository includes `weblate.yaml` to help auto-configure Weblate.

- File mask: `lib/l10n/app_*.arb`
- Template: `lib/l10n/app_en.arb`
- New language file path: `lib/l10n/app_{language}.arb`
- Monolingual: `true`
- Base language: `en`

Recommended Weblate add-ons:
- “JSON/ARB reformat” to keep formatting stable.
- “String freeze” (when preparing releases).
- Checks for placeholders to ensure `{name}`, `{count}`, etc. are preserved.

## Generated Files Policy

- Generated localization Dart files are NOT committed. They are ignored via `.gitignore` and generated during CI/build.
- Run `flutter gen-l10n` locally when you need IDE completion, or rely on `flutter run` which generates them automatically.

## Common Tasks

- Regenerate after ARB edits:
  - `flutter gen-l10n --arb-dir=lib/l10n --output-dir=lib/l10n --template-arb-file=app_en.arb --output-localization-file=app_localizations.dart`
- Validate:
  - `flutter analyze`