Введение

Библиотека generaltranslation — это основная i18n‑библиотека GT, содержащая утилиты и классы для перевода и форматирования. Чаще всего её используют с пакетами фреймворков, такими как gt-next и gt-react, но она также может использоваться как самостоятельная библиотека.

import { GT } from 'generaltranslation';

const gt = new GT({
  apiKey: 'your-api-key',
  projectId: 'your-project-id',
  sourceLocale: 'en',
  targetLocale: 'es',
});

// Перевод контента
const result = await gt.translate('Hello, world!', 'es');
// "¡Hola, mundo!"

// Форматирование чисел, дат, валют
const formattedPrice = gt.formatCurrency(29.99, 'USD');
const formattedDate = gt.formatDateTime(new Date());
// "$29.99"
// "9/25/2025"

// Работа с локалями
const localeProps = gt.getLocaleProperties('fr-CA');
const isValid = gt.isValidLocale('de');
// { language: "fr", region: "CA", ... }
// true

Установка

npm install generaltranslation

yarn add generaltranslation

bun add generaltranslation

pnpm add generaltranslation

Примеры

Есть два основных типа перевода: перевод строк и перевод файлов.

Настройка

Чтобы включить перевод, укажите идентификатор проекта и API‑ключ. Подробности см. в описании метода constructor.

const gt = new GT({
  apiKey: 'your-api-key',
  projectId: 'your-project-id',
  targetLocale: 'es',
});

Перевод строк

Дополнительные сведения см. в методе translate.

try {
  const result = await gt.translate('Привет, мир!');
  console.log(result); // "¡Hola, mundo!"
} catch (error) {
  console.error('Ошибка перевода:', error.message);
}

Перевод файлов

Файлы переводятся как задачи. Вы запускаете задачу, загрузив файл. Загрузка нескольких файлов запустит несколько задач.

Ознакомьтесь с методами uploadSourceFiles и checkFileTranslations для получения подробной информации.

// Файлы для загрузки
const files = [
  {
    source: {
      fileName: 'src/components/Button.tsx',
      fileFormat: 'TSX',
      locale: 'en',
      content: '...',
    },
  },
];

// Загрузка исходных файлов
await gt.uploadSourceFiles(files);

Содержание

Класс GT

Основной класс для работы с переводами и локалями:

• Constructor — инициализация экземпляра GT с конфигурацией
• setConfig — обновление конфигурации экземпляра GT

Методы перевода

• translate - Основная функция перевода
• translateMany - Пакетный перевод
• setupProject - Инициализация проекта
• shouldSetupProject - Проверка, требуется ли настройка проекта
• checkSetupStatus - Проверка статуса настройки проекта
• getProjectData - Получение данных о проекте
• uploadSourceFiles - Загрузка исходных файлов для перевода
• enqueueFiles - Постановка файлов в очередь на обработку
• checkFileTranslations - Проверка статуса перевода
• downloadTranslatedFile - Загрузка одного переведённого файла
• downloadFileBatch - Загрузка нескольких переведённых файлов
• querySourceFile - Запрос информации об исходном файле

Методы форматирования

• formatMessage - Форматирование текста с учетом локали
• formatNum - Форматирование чисел
• formatDateTime - Форматирование даты и времени

Методы работы с локалями

• getLocaleName - Получить отображаемое имя локали
• getLocaleProperties - Получить подробную информацию о локали
• getLocaleDirection - Получить направление письма для локали
• getLocaleEmoji - Получить эмодзи флага для локали
• getRegionProperties - Получить сведения и свойства региона
• isValidLocale - Проверить валидность кода локали
• resolveAliasLocale - Преобразовать канонические локали в псевдонимы
• resolveCanonicalLocale - Преобразовать локали‑псевдонимы в каноническую форму
• standardizeLocale - Привести формат кода локали к стандарту
• isSameDialect - Проверить, представляют ли локали один и тот же диалект
• isSameLanguage - Проверить, представляют ли локали один и тот же язык
• isSupersetLocale - Проверить иерархические связи локалей
• determineLocale - Определить наилучшую подходящую локаль из предпочтений
• requiresTranslation - Определить, требуется ли перевод

Утилитарные функции

Функции форматирования

• formatMessage - Независимое форматирование текста
• formatNum - Независимое форматирование чисел
• formatDateTime - Независимое форматирование даты и времени

Функции для локалей

• getLocaleName - Отдельная утилита для названия локали
• getLocaleProperties - Отдельный модуль свойств локали
• getLocaleDirection - Отдельная утилита для направления текста
• getLocaleEmoji - Отдельная утилита для эмодзи
• getRegionProperties - Отдельная утилита свойств региона
• isValidLocale - Отдельная проверка валидности локали
• resolveAliasLocale - Отдельная утилита для разрешения алиасов локалей
• standardizeLocale - Отдельная утилита стандартизации локали
• isSameDialect - Отдельная утилита сравнения диалектов
• isSameLanguage - Отдельная утилита сравнения языков
• isSupersetLocale - Отдельная проверка иерархии локалей
• determineLocale - Отдельная утилита для согласования локали
• requiresTranslation - Отдельная проверка необходимости перевода

Типы и интерфейсы

Определения TypeScript:

• GTConstructorParams - Параметры конфигурации
• LocaleProperties - Подробная информация о локали
• TranslationResult - Типы ответов сервиса перевода
• TranslateManyResult - Ответ пакетного перевода
• FileToTranslate - Конфигурация перевода файла
• EnqueueFilesOptions - Параметры постановки файлов в очередь
• Entry - Структура записи перевода
• EntryMetadata - Метаданные записи
• Content - Определения типов контента
• Variable - Структура переменной
• VariableType - Определения типов переменных
• JsxElement - Тип JSX‑элемента
• JsxChild - Тип дочернего JSX‑элемента
• JsxChildren - Тип дочерних JSX‑элементов
• DataFormat - Спецификации формата данных
• CustomMapping - Конфигурация пользовательского сопоставления

Дальнейшие шаги

• Начните работу с классом GT
• Изучите методы перевода
• Узнайте о средствах для работы с локалями
• Ознакомьтесь с вариантами форматирования
• Просмотрите отдельные функции

Для использования в конкретных фреймворках см. документацию по Next.js и React.