Массивы локализации PHP

Что такое массивы локализации PHP?

Файлы локализации PHP используют синтаксис массивов для хранения переводимых строк. Обычно они применяются в PHP-фреймворках, например, Laravel, для управления мультиязычными приложениями.

Например:

<?php

return [
    'Hello, world!',
    'Welcome to MyApp',

    'welcome_message' => 'Welcome!',
    'error_text'      => 'Something went wrong',

    'navigation' => [
        'home'    => 'Home',
        'about'   => 'About',
        'contact' => 'Contact',
    ],
];

Что такое Lingo.dev CLI?

Lingo.dev CLI — это бесплатный open-source CLI для перевода приложений и контента с помощью AI. Он создан, чтобы заменить традиционные системы управления переводами и легко интегрируется в существующие пайплайны.

Подробнее см. в разделе Обзор.

О данном руководстве

В этом гайде рассказывается, как переводить PHP-файлы локализации с помощью Lingo.dev CLI.

Вы узнаете, как:

Создать проект с нуля
Настроить пайплайн перевода
Генерировать переводы с помощью AI

Что потребуется

Для работы с Lingo.dev CLI убедитесь, что установлен Node.js v18+ :

❯ node -v
v22.17.0

Шаг 1. Создайте проект

В директории вашего проекта создайте файл i18n.json:

{
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.10",
  "locale": {
    "source": "en",
    "targets": ["es"]
  },
  "buckets": {}
}

Этот файл определяет поведение пайплайна перевода: какие языки использовать и где на файловой системе находится контент для локализации.

Подробнее о доступных свойствах читайте в разделе i18n.json.

Шаг 2. Настройте исходную локаль

Исходная локаль — это оригинальный язык и регион, на которых был написан ваш контент. Чтобы её настроить, укажите свойство locale.source в файле i18n.json:

{
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.10",
  "locale": {
    "source": "en",
    "targets": ["es"]
  },
  "buckets": {}
}

Исходная локаль должна быть указана в формате BCP 47 language tag.

Полный список кодов локалей, поддерживаемых Lingo.dev CLI, смотрите в разделе Поддерживаемые коды локалей.

Шаг 3. Настройка целевых локалей

Целевые локали — это языки и регионы, на которые вы хотите перевести свой контент. Чтобы настроить целевые локали, укажите свойство locale.targets в файле i18n.json:

{
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.10",
  "locale": {
    "source": "en",
    "targets": ["es"]
  },
  "buckets": {}
}

Шаг 4. Создание исходного контента

Если вы ещё не сделали этого, создайте один или несколько PHP-файлов локализации, которые содержат переводимый контент. Эти файлы должны находиться по пути, который включает исходную локаль (например, в виде имени директории как en/ или как часть имени файла, например messages.en.php).

Шаг 5. Создайте bucket

В файле i18n.json добавьте объект "php" в объект buckets:

{
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.10",
  "locale": {
    "source": "en",
    "targets": ["es"]
  },
  "buckets": {
    "php": {}
  }
}

В объекте "php" определите массив из одного или нескольких паттернов include:
```
{
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.10",
  "locale": {
    "source": "en",
    "targets": ["es"]
  },
  "buckets": {
    "php": {
      "include": ["./[locale]/example.php"]
    }
  }
}
```
Эти паттерны определяют, какие файлы переводить.

Сами паттерны:
- должны содержать [locale] как плейсхолдер для выбранной локали
- могут указывать на пути к файлам (например, "[locale]/messages.php")
- могут использовать звёздочки как подстановочные знаки (например, "[locale]/*.php")
Рекурсивные glob-паттерны (например, **/*.php) не поддерживаются.

Шаг 6. Настройка LLM

Lingo.dev CLI использует большие языковые модели (LLM) для перевода контента с помощью ИИ. Чтобы использовать одну из этих моделей, вам нужен API-ключ от поддерживаемого провайдера.

Чтобы начать как можно быстрее, рекомендуем использовать Lingo.dev Engine — нашу собственную платформу с бесплатным лимитом 10 000 токенов в месяц:

Зарегистрируйтесь в Lingo.dev.
Выполните следующую команду:
```
npx lingo.dev@latest login
```
Это откроет ваш браузер по умолчанию и попросит пройти аутентификацию.
Следуйте инструкциям.

Шаг 7. Генерация переводов

В каталоге, где находится файл i18n.json, выполните следующую команду:

npx lingo.dev@latest run

Эта команда:

Считывает файл i18n.json.
Находит файлы, которые нужно перевести.
Извлекает переводимый контент из файлов.
Использует настроенную LLM для перевода извлечённого контента.
Записывает переведённый контент обратно в файловую систему.

При первой генерации переводов создаётся файл i18n.lock. Этот файл отслеживает, какой контент уже переведён, чтобы избежать лишних повторных переводов при следующих запусках.

Пример

en/example.php

<?php

return [
    'Hello, world!',
    'Welcome to MyApp',

    "It's \"simple\" with a backslash \\ and newline\nAll text here",

    'welcome_message' => 'Welcome!',
    'error_text'      => 'Something went wrong',

    'navigation' => [
        'home'    => 'Home',
        'about'   => 'About',
        'contact' => 'Contact',
    ],

    'forms' => [
        'login' => [
            'username_label' => 'Username',
            'password_label' => 'Password',
            'submit_button'  => 'Sign In',
        ],
    ],

    'mixed_content' => [
        'title'        => 'Settings',
        'count'        => 42,
        'enabled'      => true,
        'nothing_here' => null,
        'description'  => 'App settings and preferences',
    ],
];

es/example.php

<?php

return [
    '¡Hola, mundo!',
    'Bienvenido a MyApp',

    "Es \"simple\" con una barra invertida \\ y salto de línea\nTodo el texto aquí",

    'welcome_message' => '¡Bienvenido!',
    'error_text'      => 'Algo salió mal',

    'navigation' => [
        'home'    => 'Inicio',
        'about'   => 'Acerca de',
        'contact' => 'Contacto',
    ],

    'forms' => [
        'login' => [
            'username_label' => 'Nombre de usuario',
            'password_label' => 'Contraseña',
            'submit_button'  => 'Iniciar sesión',
        ],
    ],

    'mixed_content' => [
        'title'        => 'Configuración',
        'count'        => 42,
        'enabled'      => true,
        'nothing_here' => null,
        'description'  => 'Configuración y preferencias de la aplicación',
    ],
];

i18n.json

{
  "version": "1.10",
  "locale": {
    "source": "en",
    "targets": ["es"]
  },
  "buckets": {
    "php": {
      "include": ["./[locale]/example.php"]
    }
  },
  "$schema": "https://lingo.dev/schema/i18n.json"
}

i18n.lock

version: 1
checksums:
  0ee8d6907f60fa2cc288cc0503ecbba1:
    "0": 0468579ef2fbc83c9d520c2f2f1c5059
    "1": d1c3a9f35e377554a4ccaa467ca26614
    "2": 769caedbdc5246bb9fee615739534bbd
    3/welcome_message: 8778dc41547a2778d0f9482da989fc00
    4/error_text: a3cd2f01c073f1f5ff436d4b132d39cf
    5/navigation/home: 104a3db3b671c04e167eafbe21e57881
    5/navigation/about: 944521eeeed2511833d2299931273c71
    5/navigation/contact: 9afa39bc47019ee6dec6c74b6273967c
    6/forms/login/username_label: 2ee65bc2dd2f12cf2672f95b2a054bf8
    6/forms/login/password_label: 223a61cf906ab9c40d22612c588dff48
    6/forms/login/submit_button: ec7b8f314fe9bc6591006707484ede61
    7/mixed_content/title: 8df6777277469c1fd88cc18dde2f1cc3
    7/mixed_content/description: 063afcd2ea84a82a1acc8f5c9fd8e42f