Структура файлов для совместной работы

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

Базовый принцип организации переводов

i18next опирается на концепцию языков (locales) и пространств имён (namespaces). Это определяет фундаментальную структуру каталогов:

  • язык — верхний уровень
  • namespace — логическое разделение домена переводов
  • ключи — конкретные строки интерфейса

Типовая структура:

/locales
  /en
    common.json
    auth.json
    dashboard.json
  /ru
    common.json
    auth.json
    dashboard.json
  /kk
    common.json
    auth.json
    dashboard.json

Такое разбиение позволяет:

  • изолировать языки друг от друга
  • синхронизировать структуру ключей между переводами
  • минимизировать конфликты в Git при параллельной работе

Разделение по namespaces

Namespaces в i18next — ключевой инструмент масштабирования. Вместо одного большого файла переводов используется набор логических модулей:

  • common — общие элементы интерфейса (кнопки, ошибки, системные сообщения)
  • auth — авторизация, регистрация, восстановление пароля
  • profile — пользовательские данные
  • dashboard — панели управления
  • validation — сообщения валидации форм

Пример структуры:

/locales
  /en
    common.json
    auth.json
    profile.json

Пример содержимого auth.json:

{
  "login": "Login",
  "logout": "Logout",
  "errors": {
    "invalid_credentials": "Invalid email or password",
    "blocked_account": "Account is blocked"
  }
}

Такой подход уменьшает вероятность пересечений ключей и упрощает работу нескольких разработчиков одновременно.

Feature-based структура (рекомендуемая для командной разработки)

При развитии проекта более устойчивой становится структура, привязанная не к типу перевода, а к функциональным модулям приложения.

/locales
  /en
    /auth
      login.json
      register.json
    /cart
      cart.json
      checkout.json
  /ru
    /auth
      login.json
      register.json
    /cart
      cart.json
      checkout.json

Преимущества:

  • перевод живёт рядом с функциональностью
  • проще поддерживать код и переводы одновременно
  • уменьшается когнитивная нагрузка при навигации

Недостатки:

  • увеличивается количество файлов
  • требуется строгая дисциплина именования

Гранулярность ключей и файлов

Слишком крупные файлы переводов создают узкие места при работе в команде. Оптимальная гранулярность зависит от размера проекта:

  • малые проекты: 2–5 namespaces
  • средние: 5–15 namespaces
  • крупные: feature-based структура с десятками файлов

Пример чрезмерно крупного файла (антипаттерн):

common.json (5000+ ключей)

Проблемы:

  • частые конфликты в Git
  • сложность ревью изменений
  • высокий риск дублирования ключей

Подход к именованию ключей

Структура ключей влияет на читаемость и повторное использование:

Нестрогий вариант (плоский)

{
  "loginButton": "Login",
  "logoutButton": "Logout"
}

Проблемы:

  • сложно группировать
  • плохо масштабируется

Иерархический вариант

{
  "auth": {
    "login": "Login",
    "logout": "Logout"
  }
}

Иерархия:

  • уменьшает количество конфликтов
  • позволяет логически группировать сущности
  • улучшает навигацию по файлам

Разделение по окружениям и сборке

В реальных проектах структура часто дополняется разделением по окружениям:

/locales
  /en
    common.json
    common.override.json

или:

/locales
  /en
    common.json
  /en-override
    common.json

Это используется для:

  • A/B тестирования текстов
  • временных правок без изменения базовых переводов
  • кастомизации для клиентов (white-label)

Динамическая загрузка переводов

При использовании backend-загрузчиков (например, i18next-http-backend) структура файлов становится частью API:

/public/locales/en/common.json
/public/locales/ru/common.json

Загрузка происходит по шаблону:

/locales/{lng}/{ns}.json

Это требует строгого соблюдения:

  • одинаковой структуры ключей во всех языках
  • синхронизации namespaces
  • отсутствия расхождений между языковыми файлами

Разделение по доменам приложения

В сложных системах применяют доменное разделение:

/locales
  /en
    /billing
    /notifications
    /users
    /admin

Каждый домен:

  • изолирован логически
  • может иметь собственную команду разработчиков
  • может обновляться независимо

Конфликты при командной работе и их источники

Наиболее частые причины конфликтов в Git при работе с i18next:

  1. Общий файл переводов

    • одновременное редактирование разных ключей

  2. Отсутствие namespaces

    • все строки находятся в одном JSON

  3. Несогласованная структура ключей

    • разные разработчики создают разные иерархии

  4. Ручное добавление языков

    • отсутствие генерации или синхронизации структуры

Минимизация конфликтов достигается через:

  • дробление файлов
  • feature-based структуру
  • автоматическую проверку ключей

Синхронизация структуры между языками

Критически важно, чтобы структура JSON совпадала:

en/auth.json
ru/auth.json
kk/auth.json

Несоответствие структуры приводит к:

  • fallback-значениям
  • пропущенным переводам
  • runtime-ошибкам в интерфейсе

Для контроля применяются:

  • линтеры переводов
  • CI-проверки структуры JSON
  • генерация шаблонов переводов

Автоматизация генерации структуры

В крупных проектах структура переводов часто генерируется автоматически:

  • из TypeScript типов
  • из компонентов UI
  • из design system
  • из backend схем

Пример генерации базового файла:

i18n extract → keys.json → locales/{lng}/{ns}.json

Такой подход позволяет:

  • избегать ручного создания ключей
  • поддерживать единый источник правды
  • синхронизировать UI и переводы

Использование индексных файлов

Для упрощения импорта используют index-файлы:

/locales
  /en
    index.js

Пример:

import common from './common.json'
import auth from './auth.json'

export default {
  common,
  auth
}

Это облегчает:

  • сборку переводов
  • подключение в i18next
  • реэкспорт namespaces

Масштабирование структуры при росте проекта

По мере роста проекта структура обычно эволюционирует:

  1. один файл переводов
  2. разделение по языкам
  3. введение namespaces
  4. feature-based структура
  5. доменное разделение
  6. частичная автоматизация генерации

Критическим моментом становится переход от “ручного редактирования JSON” к “системе управления переводами”, где структура файлов лишь отражает внутреннюю модель данных, а не является единственным источником управления текстами интерфейса

Оглавление