Как я превратил скрипты локализации в npm-библиотеку / Хабр

Привет, Хабр! Это продолжение первой статьи, где я автоматизировал перевод 10 000 строк скриптами. Скрипты оказались полезными — решил оформить в npm-пакет.

Что изменилось

Было: 4 отдельных скрипта, которые нужно копировать в проект.

Стало: npm install -D i18next-toolkit и готово.

# Раньше
node scripts/extract-russian.mjs --mode=report
node scripts/sync-locales.mjs
node scripts/translate-locales.mjs

# Теперь
npx i18next-toolkit extract
npx i18next-toolkit update  # sync + translate одной командой

Что добавил

1. Конфиг вместо хардкода

i18next-toolkit init

Создаёт .i18next-toolkitrc.json:

{
  "localesPath": "public/locales",
  "sourceLanguage": "ru",
  "targetLanguages": ["en", "kk"],
  "include": "src/**/*.{ts,tsx,js,jsx}",
  "batchSize": 50,
  "concurrency": 5
}

Больше не нужно лезть в код скрипта чтобы поменять пути.

2. Watch-режим

i18next-toolkit watch

Следит за изменениями файлов и автоматически извлекает новые строки. Удобно при разработке.

3. Кэширование переводов

Переводы сохраняются в .i18next-toolkit-cache.json. Повторный запуск не тратит API-запросы на уже переведённые строки.

4. Статистика и диффы

# Сколько переведено
i18next-toolkit stats
# ru: 100% (9823/9823)
# en: 95% (9332/9823)
# kk: 87% (8546/9823)

# Что отличается между языками
i18next-toolkit diff --source=ru --target=en

5. Валидация для CI

i18next-toolkit validate --strict
i18next-toolkit sort --check

Проверяет:

Пустые значения
Несовпадение интерполяций ({{name}} в ru, но {{user}} в en)
Лишние/недостающие ключи
Сортировку ключей

6. Поддержка любых языков

В первой версии был хардкод на русский. Теперь:

# Китайский
i18next-toolkit extract --source-pattern="[\u4e00-\u9fff]"

# Арабский
i18next-toolkit extract --source-pattern="[\u0600-\u06FF]"

7. Очистка неиспользуемых ключей

i18next-toolkit clean --dry-run
# Found 47 unused keys
# - extracted.old_button
# - extracted.deprecated_label
# ...

i18next-toolkit clean  # удалить

CLI команды

Команда	Что делает
`extract`	Находит строки, заменяет на `t()`
`sync`	Синхронизирует структуру JSON
`translate`	Переводит через Google Translate
`update`	sync + translate одной командой
`watch`	Следит за файлами
`stats`	Показывает покрытие
`diff`	Сравнивает языки
`clean`	Удаляет неиспользуемые ключи
`sort`	Сортирует ключи по алфавиту
`validate`	Проверяет на ошибки
`find-missing`	Ищет ключи без перевода

Программный API

import { extract, sync, translate, update } from 'i18next-toolkit';

// Извлечь строки
await extract({
  mode: 'extract',
  include: 'src/**/*.tsx',
  autoGetters: true,  // решает проблему с константами
});

// Синхронизировать + перевести
await update({
  sourceLanguage: 'ru',
  targetLanguages: ['en', 'de', 'fr'],
});

CI/CD

# .github/workflows/i18n.yml
name: i18n Check

on: [push, pull_request]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
      - run: npm ci
      - run: npx i18next-toolkit validate --strict
      - run: npx i18next-toolkit sort --check
      - run: npx i18next-toolkit find-missing

Теперь PR не пройдёт если:

Есть пустые переводы
Ключи не отсортированы
Есть использование несуществующих ключей

Установка

npm install -D i18next-toolkit
# или
yarn add -D i18next-toolkit
# или
pnpm add -D i18next-toolkit

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

# 1. Установить
npm install -D i18next-toolkit

# 2. Создать конфиг
npx i18next-toolkit init

# 3. Посмотреть что найдётся
npx i18next-toolkit extract

# 4. Извлечь и перевести
npx i18next-toolkit extract --mode=extract
npx i18next-toolkit update

npm: npmjs.com/package/i18next-toolkit
GitHub: github.com/Niyaz-Mazhitov/i18next-toolkit

Буду рад фидбеку, issues и PR.

Как я превратил скрипты локализации в npm-библиотеку