chore: prepare for weblate

docs/localization.md

@@ -1,65 +1,63 @@
-## Localization (i18n)
+# Localization Guidelines
 
-- Supported locales: `en`, `de`, `fr`, `it`.
-- Uses Flutter's `gen_l10n` with ARB files and the `intl` package for date/number formatting.
+This app uses Flutter's gen-l10n with ARB files in `lib/l10n`.
 
-### Install & Generate
+- 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)
 
-- Install packages:
-  - `flutter_localizations` (Flutter SDK)
-  - `intl: ^0.20.2`
-- Files are under `lib/l10n/*.arb`. The template is `app_en.arb`.
-- Generate localizations:
-  - `flutter gen-l10n`
-  - or run a full build: `flutter pub get && flutter gen-l10n`
+## Adding New Strings
 
-### Usage Examples
+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)`.
 
-- Basic text:
-  - `Text(AppLocalizations.of(context)!.appTitle)`
-- With placeholder:
-  - `Text(AppLocalizations.of(context)!.dynamicContentWithPlaceholder('Alex'))`
-- Pluralization:
-  - `Text(AppLocalizations.of(context)!.itemsCount(3))`
-- Date/time formatting:
-  - `final dateText = DateFormat.yMMMMEEEEd(Localizations.localeOf(context).toString()).format(DateTime.now());`
-  - `Text(dateText)`
-- Number formatting:
-  - `final price = NumberFormat.currency(locale: Localizations.localeOf(context).toString(), symbol: '€').format(1234.56);`
-  - `Text(price)`
+## Placeholders and ICU
 
-### Add a New Language
+- 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" } } }
+  ```
 
-- Create a new ARB file in `lib/l10n/`, e.g. `app_es.arb`.
-- Copy keys from `app_en.arb` and provide translated values.
-- Ensure placeholders and plural rules match the template.
-- Add the locale to `supportedLocales` in `MaterialApp` (see `lib/main.dart`).
-- Regenerate: `flutter gen-l10n`.
+## Punctuation and Style
 
-### Best Practices
+- Prefer typographic ellipsis `…` over `...`.
+- Keep capitalization consistent across locales.
+- Avoid embedding brand names in placeholders; keep them literal in strings.
 
-- Key naming: use lowerCamelCase (e.g., `loginButton`, `errorMessage`).
-- Include `@` metadata with `description` for context and `placeholders` with examples.
-- Prefer ICU plural/select syntax for quantities and genders.
-- Avoid concatenating strings at runtime; use placeholders in ARB.
+## Weblate
 
-### In‑App Locale Switching
+This repository includes `weblate.yaml` to help auto-configure Weblate.
 
-- Open the Profile page → Settings tile → choose `System`, `English`, `Deutsch`, `Français`, or `Italiano`.
-- Selection persists across app launches.
+- 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`
 
-### Troubleshooting
+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.
 
-- Build fails with ARB placeholder errors:
-  - Ensure every placeholder has an example string and correct type.
-- Missing translation at runtime:
-  - Flutter falls back to English; search for hard‑coded strings and replace with `AppLocalizations`.
-- iOS strings not changing:
-  - Restart the app after changing system language or use the in‑app language selector.
+## Generated Files Policy
 
-### References
-
-- Flutter localization: https://docs.flutter.dev/ui/accessibility-and-localization/internationalization
-- Intl package: https://pub.dev/packages/intl
+- 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`