# Добавление своего языка

XC_VM использует файловую систему переводов. Каждый язык — это один `.ini` файл в директории `src/resources/langs/`. Добавление нового языка не требует изменений в коде — достаточно создать файл, и он автоматически появится в панели администратора.

## Быстрый старт

1. Скопируйте английский файл как шаблон:

```bash
cp src/resources/langs/en.ini src/resources/langs/xx.ini
```

Замените `xx` на код языка по стандарту [ISO 639-1](https://ru.wikipedia.org/wiki/ISO_639-1) (например, `it` — итальянский, `pl` — польский, `ja` — японский).

2. Откройте `xx.ini` и переведите значения (правая часть от `=`):

```ini
[Language]
a_to_z = "От А до Я"       ; ← переведите это
access_code = "Код доступа" ; ← переведите это
actions = "Действия"        ; ← переведите это
```

3. Перейдите в **Settings → Interface → Interface Language** и выберите новый код языка.

Готово. Перезагрузка не требуется.

## Формат файла

Каждый `.ini` файл имеет следующую структуру:

```ini
[Language]
key = "Переведённый текст"
another_key = "Другой переведённый текст"
```

**Правила:**

- Заголовок секции `[Language]` **обязателен** в первой строке.
- Ключи — идентификаторы в формате `snake_case` — **не изменяйте их**.
- Значения должны быть заключены в **двойные кавычки**.
- Строки отсортированы по ключу в алфавитном порядке.
- Кодировка файла — **UTF-8** (без BOM).

## Как это работает

| Этап | Что происходит |
|------|----------------|
| Загрузка панели | `Translator::init()` сканирует `src/resources/langs/` на наличие `*.ini` файлов |
| Список языков | `Translator::available()` возвращает все найденные коды языков |
| Выбор пользователя | Язык сохраняется в cookie `lang` (для каждого браузера) и в колонке `settings.language` в БД (глобальный язык по умолчанию) |
| Отсутствующий ключ | Если ключ перевода используется в коде, но отсутствует в вашем `.ini` файле, система **автоматически добавит** его с именем ключа в качестве значения по умолчанию |

## Доступные языки

| Код | Файл |
|-----|------|
| `bg` | `bg.ini` — болгарский |
| `de` | `de.ini` — немецкий |
| `en` | `en.ini` — английский (эталон) |
| `es` | `es.ini` — испанский |
| `fr` | `fr.ini` — французский |
| `pt` | `pt.ini` — португальский |
| `ru` | `ru.ini` — русский |

## Советы

- **Всегда используйте `en.ini` как источник истины** — он содержит все ключи. В других файлах могут отсутствовать ключи, которые автоматически заполняются при работе.
- **Автоматическое создание ключей**: если в вашем файле отсутствует ключ, `Translator` автоматически добавит строку `key = "key"`. Потом можно найти и перевести их.
- **Поиск непереведённых ключей** — ищите строки, где ключ равен значению:

```bash
grep -P '^(\w+)\s*=\s*"\1"$' src/resources/langs/xx.ini
```

- **Валидация файла** — убедитесь, что `parse_ini_file()` читает его корректно:

```bash
php -r "var_dump(parse_ini_file('src/resources/langs/xx.ini', false, INI_SCANNER_RAW));" | head -20
```

## Вклад в проект

Чтобы добавить свой перевод в проект:

1. Форкните репозиторий.
2. Создайте файл языка по инструкции выше.
3. Отправьте Pull Request с новым `.ini` файлом.

Убедитесь, что все ключи из `en.ini` присутствуют и переведены.

## Связанные файлы

| Файл | Роль |
| --- | --- |
| `src/Core/Localization/Translator.php` | Поиск переводов |
| `src/resources/langs/` | Файлы языков |
