@daniil203/i18n NPM

Установка

Для установки библиотеки используйте команду:

npm install @daniil203/i18n

Использование

Импорт библиотеки и создание экземпляра

После установки, чтобы начать использовать библиотеку, создайте экземпляр I18n, передав в него объект с настройками, включая переводы, активный язык и язык для записи.

// i18n/index.ts
import { I18n } from "@daniil203/i18n";
import * as translations from "./translations";  // Импортируйте ваши переводы

export const i18n = new I18n({
    translations,
    activeLang: "ru",  // Язык, на который будет происходить перевод
    writeLang: "ru"    // Язык, на котором пишутся исходные строки
});

Формирование файлов локализации

Файлы локализации — это объекты, где ключами являются строки, которые будут переведены, а значениями — переводы для различных языков.

Пример структуры файла локализации:

// translations/ru.json
{
    "Привет": "Привет",
    "Hello": "Привет",
}

// translations/en.json
{
    "Привет": "Hello",
    "Hello": "Hello",
}

// translations/kk.json
{} 
// В файле должен быть пустой объект либо заполненный переводами
// нельзя файл оставлять пустым или массивом [] - вызовится ошибка типов

Пример структуры экспорта файлов локализации:

// translations/index.ts
import be from "./be.json";
import en from "./en.json";
import kk from "./kk.json";
import pl from "./pl.json";
import ru from "./ru.json";
import uz from "./uz.json";
export { be, en, kk, pl, ru, uz };

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

Для перевода текста используйте метод t. Он позволяет переводить строки, основываясь на текущем активном языке.

import { i18n } from './i18n';

const greeting = i18n.t("Привет");  // Получаем перевод строки "Привет" на текущий активный язык
console.log(greeting);  // Выведет "Hello" (если активный язык "en")
// Если вы передаёте в метод текст на языке отличном что указан в writeLang, то нужно передавать второй параметр

const greeting = i18n.t("Hello", "en");
console.log(greeting); // Выведет "Привет" (если активный язык "ru")

Если перевод для активного языка отсутствует, метод вернет исходный текст или текст на языке записи.

Изменение активного языка

Вы можете изменить активный язык, используя метод setActiveLang.

i18n.setActiveLang("en");  // Устанавливаем активный язык как английский

Теперь все переводы, получаемые через t, будут возвращать строки на английском языке.

Получение всех переводов

Чтобы получить все переводы для всех языков, используйте метод getAllTranslations.

const allTranslations = i18n.getAllTranslations();
console.log(allTranslations);  // Выведет все переводы для всех языков

Получение списка доступных языков

Для получения списка всех поддерживаемых языков, используйте метод getLangs.

const langs = i18n.getLangs();
console.log(langs);  // Вернет список языков, например: ["ru", "en"]

Подписка на изменения языка

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

const unsubscribe = i18n.subscribe(() => {
    console.log("Язык изменился на", i18n.activeLang);
});

// Чтобы отписаться от изменений, вызовите returned функцию
unsubscribe();

Этот метод добавляет слушателя, который будет оповещён каждый раз, когда активный язык изменится. Возвращаемая функция позволяет отписаться от уведомлений.

Как передавать локализацию

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

Импортируйте локализацию в вашем приложении.

Передайте объект с переводами в экземпляр класса I18n.

Пример передачи локализации:

// i18n/index.ts
import { I18n } from "@daniil203/i18n";
import * as translations from "./translations";

export const i18n = new I18n({
    translations,
    activeLang: "ru",
    writeLang: "ru"
});

i18n.t("Привет") // Выведет "Привет"
i18n.t("Hello", "en") // Выведет "Привет"

i18n.setActiveLang("en")

i18n.t("Привет") // Выведет "Hello"
i18n.t("Hello", "en") // Выведет "Hello"

Использование в React

Для интеграции библиотеки с вашим React-приложением можно создать хук, который будет подписываться на изменения активного языка и инициировать перерисовку компонента при изменении языка.

Шаг 1: Создание экземпляра I18n Импортируйте класс I18n, создайте экземпляр и передайте настройки для переводов, активного языка и языка записи.

import { I18n } from "@daniil203/i18n";
import * as translations from "src/i18n/translations"; // Импорт ваших переводов

export const i18n = new I18n({
    translations,
    activeLang: "ru",  // Установите активный язык
    writeLang: "ru",   // Язык для записи исходных строк
});

Шаг 2: Создание хука useI18n

Создайте хук, который будет возвращать функцию перевода. Этот хук подписывается на изменения активного языка, чтобы перерисовывать компонент при изменении языка.

import { useEffect, useState } from "react";
import { i18n } from "src/i18n";  // Экземпляр i18n

export function useI18n() {
    const [, forceRender] = useState(0);

    // Подписываемся на изменения активного языка
    useEffect(() => {
        const unsubscribe = i18n.subscribe(() => {
            forceRender((n) => n + 1); // Перерисовываем компонент
        });

        return () => {
            unsubscribe(); // Отписка при размонтировании компонента
        };
    }, []);

    return i18n.t.bind(i18n); // Возвращаем метод перевода
}

Шаг 3: Использование хука в компонентах

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

import React from "react";
import { useI18n } from "./i18n"; // Импортируйте хук

const MyComponent = () => {
    const t = useI18n(); // Получаем функцию для перевода

    return (
        <div>
            <h1>{t("Привет")}</h1>  {/* Перевод текста "Привет" на активный язык */}
        </div>
    );
};

export default MyComponent;

Шаг 4: Изменение активного языка Для изменения активного языка используйте метод setActiveLang. Например, для переключения на английский язык:

i18n.setActiveLang("en");  // Устанавливаем активный язык как английский

Примечание

Все компоненты, использующие хук useI18n, будут автоматически перерисовываться при изменении активного языка, благодаря подписке на изменения в экземпляре I18n.

Вы можете использовать метод t для перевода строк на любой язык, указанного в вашем объекте локализаций.

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