# Project rules

## Localization (required for every new feature)

The interface is multilingual. English is the source language: user-facing text is
written as `__('English source sentence')` and translated through flat JSON files in
`lang/{code}.json`.

When adding or changing any user-visible string:

1. Wrap it in `__()` (Blade: `{{ __('…') }}`, PHP: `__('…')`). Never hard-code display text.
2. Add the key to **every** shipped language file: `lang/fa.json`, `lang/ckb.json` and
   `lang/ar.json` (English falls back to the key itself). Admin-added languages live in
   their own `lang/{code}.json` and are edited in the console.
3. Run `php artisan lang:missing` and make sure the new key is not listed for any active
   language. `php artisan lang:missing fa` limits the report to one language.
4. Keep placeholders (`:name`, `:count`) identical across languages — Laravel replaces
   them by name.
5. Use the language's native name and set `direction` (`ltr`/`rtl`) when adding a language
   in the admin console; layouts read the direction from the `languages` table.

The admin console has **Languages** (add/enable/default/delete) and a translation editor
per language that shows every key, marks missing ones, and saves straight to the JSON
file, so operations can fix wording without a deploy.