@itcamel/text-kit

Легковесная i18n-утилита для React-приложений с поддержкой rich-текста и интерполяции переменных.

Установка

yarn add @itcamel/text-kit

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

import { initTextKit, t, tx, bind } from '@itcamel/text-kit';

import textEn from '@/shared/assets/text.en.json';
import policyEn from '@/shared/assets/privacy-policy-text/privacy-policy.en.json';
import textRu from '@/shared/assets/text.ru.json';

initTextKit({
  locales: {
    en: [textEn, policyEn],
    ru: textRu,
  },
  language: 'en',
  fallbackLanguage: 'en',
  defaultVars: {
    companyName: 'GameDevly',
    currentYear: String(new Date().getFullYear()),
  },
  shortcutRoots: ['pages'],
});

const title = t('pages.home.title');
const policy = tx('Contact us: {supportEmail}', { supportEmail: '[email protected]' });

const homeText = bind('pages.home');
const subtitle = homeText('subtitle');

API

• initTextKit(options) - инициализация словарей, активного языка, fallback-языка и defaultVars.
• registerLocaleTexts(language, texts) - добавление/слияние одного или нескольких JSON-деревьев в словарь языка.
• setDefaultVars(vars) / patchDefaultVars(vars) - полная замена или частичное обновление дефолтных переменных.
• t(key, vars?, opts?) - перевод по ключу для текущего языка.
• tLang(language, key, vars?, opts?) - перевод по ключу для конкретного языка без смены глобального состояния.
• tx(raw, vars?) - парсинг произвольной rich-строки с переменными.
• bind(baseKey, defaultVars?, defaultOpts?) - создание переводчика для namespace ключей.
• setLanguage(language) / getLanguage() / getAvailableLanguages() - управление текущим языком и списком доступных языков.
• useLanguage() - React-хук текущего языка, смены языка и списка доступных языков.
• select(key) / hasText(key) - низкоуровневые хелперы чтения.

Поддержка rich-текста

• Плейсхолдеры: {myVar} с автоматическим trim.
• Маркеры жирного: **text**, <b>text</b>.
• Переносы строк: \n, \r\n, <br>, <br/>.
• Значения переменных: string | number | boolean | ReactNode | (() => ReactNode).

Важные правила конфигурации

• language и fallbackLanguage должны быть объявлены в locales, иначе initTextKit выбросит ошибку.
• Перевод по ключу для t/tLang должен резолвиться в строку.

Публикация в npm

Пакет @itcamel/* публикуется как public (publishConfig.access). Пока идёт предрелизная линия, в publishConfig задан tag: beta: в npm это dist-tag beta, а не latest.

Установка у потребителей: yarn add @itcamel/text-kit@beta (или явная версия 1.0.0-beta.x).

1. Войти в npm под учёткой с правами на scope @itcamel:

   • npm login — токен попадает в ~/.npmrc, его читает npm publish.
   • Проверка: npm whoami (должен показать твой логин).

   Скрипты yarn publish:npm / yarn publish:dry-run вызывают npm publish, а не yarn npm publish: у Yarn часто YN0033 при публикации, потому что он не использует тот же ~/.npmrc, что и npm.

   CI без интерактива: NPM_TOKEN (classic token с правом Automation или Publish) и перед публикацией
   npm config set //registry.npmjs.org/:_authToken "${NPM_TOKEN}"
   либо одноразово npm publish с переменной окружения, как принято в твоём CI.

   В .yarnrc.yml задан npmRegistryServer: https://registry.npmjs.org — для yarn install/yarn add; публикация идёт через npm.

2. Поднять версию в package.json (вручную или npm version prerelease --preid=beta --no-git-tag-version для следующего beta.N).

3. Проверка без выкладки: yarn publish:dry-run.

4. Публикация в beta: yarn publish:npm — внутри npm publish, dist-tag и access берутся из publishConfig в package.json (tag: beta, access: public).

Когда будешь готов к стабильному релизу: убери "tag": "beta" из publishConfig и используй yarn publish:npm:latest / yarn publish:dry-run:latest, либо снова выставь тег вручную.