TypeScript - Lingo.dev CLI

Что такое локализация TypeScript?

Файлы локализации TypeScript используют синтаксис объектов TypeScript/JavaScript для хранения переводимых строк. Они часто применяются в современных веб-приложениях для типобезопасной интернационализации.

Например:

const messages = {
  navigation: {
    home: "Home",
    about: "About Us",
    contact: "Contact Us"
  },

  forms: {
    title: "Contact Form",
    nameLabel: "Your Name",
    submitButton: "Send Message"
  },
};

export default messages;

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

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

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

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

В этом руководстве объясняется, как переводить файлы локализации TypeScript с помощью Lingo.dev CLI.

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

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

Необходимые условия

Для работы с 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.

Полный список кодов локалей, поддерживаемых 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. Создайте исходный контент

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

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

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

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

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

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

Шаг 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.ts

const messages = {
  navigation: {
    home: "Home",
    about: "About Us",
    contact: "Contact Us",
    services: "Our Services"
  },

  forms: {
    title: "Contact Form",
    nameLabel: "Your Name",
    emailLabel: "Email Address",
    messageLabel: "Your Message",
    submitButton: "Send Message",
    successMessage: "Thank you for your message!",
    locked_key_1: "This value is locked and should not be changed",
    ignored_key_1: "This value is ignored and should not be processed"
  },
};

export default messages;

es/example.ts

const messages = {
  navigation: {
    home: "Inicio",
    about: "Sobre Nosotros",
    contact: "Contáctanos",
    services: "Nuestros Servicios"
  },

  forms: {
    title: "Formulario de Contacto",
    nameLabel: "Tu Nombre",
    emailLabel: "Dirección de Correo Electrónico",
    messageLabel: "Tu Mensaje",
    submitButton: "Enviar Mensaje",
    successMessage: "¡Gracias por tu mensaje!",
    locked_key_1: "This value is locked and should not be changed",
  },
};

export default messages;

i18n.json

{
  "version": "1.10",
  "locale": {
    "source": "en",
    "targets": ["es"]
  },
  "buckets": {
    "typescript": {
      "include": ["./[locale]/example.ts"],
      "lockedKeys": ["locked_key_1"],
      "ignoredKeys": ["ignored_key_1"]
    }
  },
  "$schema": "https://lingo.dev/schema/i18n.json"
}

i18n.lock

version: 1
checksums:
  0cdc4f3ba34edc7f3ba4d996158306ad:
    navigation/home: 104a3db3b671c04e167eafbe21e57881
    navigation/about: 8f89131a66d4659be07cd5af2c7ea898
    navigation/contact: 2a75337dc9603915c4ec1d1905afb7b9
    navigation/services: 999f32026e64978cb3ec794a496b0bb8
    forms/title: ac85dea7c7f0bf1cd7d48cc1b4da3acc
    forms/nameLabel: 03c6ae7996d5841f743cd406b4eff72d
    forms/emailLabel: 0ee22bbbe989a0c61a18023407d12dc2
    forms/messageLabel: 1e460d0909502d0e94b9be562643af0d
    forms/submitButton: 487177489aafc9c0243c57ef3850a2d9
    forms/successMessage: a0a7aa980dffa31d4d194af718a917b3
    forms/locked_key_1: 73fc105de1aefc3f0a97d187a80cf0a4
    forms/ignored_key_1: d88a7aa6c5661ca901ee0f4cb51e3a0d