React Locales Library

@mxvnv/locales — это библиотека для локализации в React-приложениях. Она предоставляет контекст и хуки для управления локалями и перевода текста с поддержкой плейсхолдеров.

Установка

Для установки библиотеки в проект, используйте npm или yarn:

npm install @mxvnv/locales

или

yarn add @mxvnv/locales

Пример использования

Настройка локализации

Для использования библиотеки, нужно обернуть ваше приложение в компонент LocalesProvider, который предоставляет контекст локалей, и передать ему объект с локалями.

Пример кода для настройки локализации:

import { createRoot } from 'react-dom/client';
import App from './App';
import { LocalesProvider } from '@mxvnv/locales';
import locales from './locales.json';
createRoot(document.getElementById('root')!).render(
<LocalesProvider locales={locales}><App /></LocalesProvider>
);

В данном примере мы передаем локали из JSON-файла и оборачиваем компонент App в LocalesProvider.

Использование хука useLocales

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

Пример использования хука в компоненте:

import { useLocales } from '@your-username/my-react-lib';
function App() { const { t, setLocales } = useLocales();
const translatedText = t('project.text.name', { placeholder: "плейсхолдер", greet: 'hello' });
return ( <button onClick={() => setLocales('en')}>Change to English {translatedText} ); }
export default App;

Функция перевода

useLocales возвращает объект, который содержит:

t(path: string, placeholders: object) — функция для перевода текста. Принимает путь к строке в JSON (например, project.text.name) и объект с плейсхолдерами, которые будут заменены в строке.

setLocales(locale: string) — функция для смены текущей локали. Например, для смены локали на английский можно вызвать setLocales('en').

Пример структуры локалей

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

Пример локалей: { "ru": { "project": { "text": { "name": "Привет, {greet}! Это {placeholder}" } } }, "en": { "project": { "text": { "name": "Hello, {greet}! This is {placeholder}" } } } }

В этом примере, мы используем плейсхолдеры {greet} и {placeholder}, которые могут быть заменены на динамичные значения через функцию t.

Типы

Библиотека предоставляет следующие типы для TypeScript:

LocalesProviderProps — тип для пропсов компонента LocalesProvider. TranslateFunc — тип для функции перевода t. CurrentLocale — тип для текущей локали. LocaleData — тип для данных перевода.