# Arabic language code: `sa` → `ar`

Until 2026-10 the store's Arabic had the code `sa` (Saudi Arabia's country code, and
Sanskrit in ISO 639-1). It is now `ar` everywhere: the `languages` table, every
`*_translations` table, `translations`, `business_settings`, and the search statistics.

## Deploy

```
git pull
php artisan migrate
```

Nothing else. No `.env` change, no `db:seed`, and no new app release.

- Migration `2026_10_05_000001_convert_arabic_language_code_to_ar` renames the data in a
  single transaction (about 10–15 s on a copy of live). If anything fails, nothing changes
  and the site keeps running on `sa`.
- It clears the cache itself when it finishes. Before deploying, check that `SESSION_DRIVER`
  in the live `.env` is not `cache`; otherwise clearing the cache would log everyone out.
- Run it at a quiet time.
- To see the numbers beforehand (read only): `php artisan languages:arabic-code-report`

After `migrate`, run the same command. It should print `Converted: nothing left under the
old code.` A request (an admin saving, the search statistics job) running at the exact
moment the migration finished could still write a row under `sa`. In that case the command
says so, and `php artisan languages:arabic-code-report --convert` converts the leftovers the
same way (one transaction, with a backup).

## Why nobody notices

`App\Support\ArabicLanguageCode` maps every incoming `sa` / `ar` to the code the database
actually holds. That covers:

- `.env` `DEFAULT_LANGUAGE`
- old sessions
- `?lang=sa` in old links and open admin forms
- the `App-Language` header

Between `git pull` and `migrate` the database still says `sa`, so everything behaves as
before. After `migrate` it is `ar`, and `sa` still works.

## Texts that existed under both codes

The app always asked for `ar` and the website for `sa`, so about 2,350 translation keys
existed twice. The website's text (`sa`) is kept, unless it was empty. As a result:

- **Website:** unchanged, except 10 admin labels whose Arabic was empty (they showed in
  English) and now show in Arabic.
- **App:** about 100 server messages now use the website's wording. Some texts that came
  back in English (notification types, coupon titles) now come back in Arabic.

## Rollback

`php artisan migrate:rollback --step=1` restores every row exactly from
`language_code_backups`, then drops that table. This was checked on a copy of live: all 12
tables identical, and a second migrate gives the same result again.

Roll back only shortly after the deploy. Arabic texts added after the migration stay under
`ar` and would no longer show (they are not deleted).

## Adding translations from now on

`database/translations/translations.json` holds `ar` and `en` only. Never add `sa` back.
In code, test for Arabic with `is_arabic_language($code)`, never by comparing to `'sa'`.