Mongez Localization, Самый простой способ перевести ваш сайт независимо от вашего любимого фреймворка


Введение

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

Установка

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

npm i @mongez/localization

Используя Yarn

yarn add @mongez/localization

После установки создайте файл localization-config.ts в вашем проекте (или .js, рекомендуется использовать typescript), чтобы мы могли задать наши конфигурации.

Импортируйте этот файл на ранней стадии вашего проекта, в начале src/index.ts, например, или в записи главного файла проекта.

Давайте определим наш файл конфигурации.

// localization-config.ts
import {
  TranslationsList,
  setLocalizationConfigurations,
} from "@mongez/localization";

setLocalizationConfigurations({
  /**
   * Default locale code
   */
  defaultLocaleCode: "ar",
  /**
   * Fall back locale code
   */
  fallback: "en",
});
Войти в полноэкранный режим Выйти из полноэкранного режима

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

Определение ключевых слов перевода

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

метод расширения

Основным и главным способом задания ключевых слов перевода является импортирование метода extend.

import { extend } from '@mongez/localization';

// let's add some keywords for English translations
extend('en', {
  home: 'Home Page',
  welcomeUser: 'Hello User, Welcome Home!',
  login: 'Login',
  createAccount: 'Create Account'
});

// now let's add same keywords but for Arabic
extend('en', {
  home: 'الصفحة الرئيسية',
  welcomeUser: 'مرحبا بك!',
  login: 'تسجيل الدخلو',
  createAccount: 'إنشاء حساب جديد'
});
Вход в полноэкранный режим Выйти из полноэкранного режима

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

метод trans

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

// later in your application html|views for example
import { trans } from '@mongez/localization';

console.log(trans('home')); // as default locale code is `ar` so it will return الصفحة الرئيسية
Вход в полноэкранный режим Выйти из полноэкранного режима

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

Группированные переводы

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

import { extend, groupedTranslation } from '@mongez/localization';

groupedTranslation({
  home: {
    en: 'Home Page',
    ar: 'الصفحة الرئيسية'
  },
  welcomeUser: {
    en: 'Hello User, Welcome Home!',
    ar: 'مرحبا بك!',
  },
  login: {
    en: 'Login',
    ar: 'تسجيل الدخلو',
  },
  createAccount: {
    en: 'Create Account',
    ar: 'إنشاء حساب جديد'
  }
})
Вход в полноэкранный режим Выйти из полноэкранного режима

Это более удобно для работы с переводами, так как мы убеждаемся, что каждое ключевое слово переведено для всех кодов локали, чтобы не пропустить ни один язык, однако метод extend очень полезен, если мы работаем с динамическими переводами, либо получаем их из backend api или из json файлов.

Изменение текущего кода локали

Мы можем изменить текущий код локали во время выполнения, используя метод setCurrentLocaleCode, который обновит текущий код локали.

import { trans, setCurrentLocaleCode } from '@mongez/localization';

// let's log the translation before and after we change the locale code
console.log(trans('home')); // الصفحة الرئيسية

setCurrentLocaleCode('en');

// now let's log it again
console.log(trans('home')); // Home Page
Вход в полноэкранный режим Выход из полноэкранного режима

Обратный перевод

Ранее в разделе конфигураций мы определили код резервной локали, он полезен в случае отсутствия ключа перевода в текущем коде локали, давайте покажем его в действии

import { trans, groupedTranslation } from '@mongez/localization';

groupedTranslation({
  otherUnknownKeyword: {
    en: 'Welcome Unknown keyword'
  }
});

// Remember the current locale code is `ar` so when we call `trans` method with `otherUnknownKeyword`
// the keyword does not have any translation in `ar`, the fallback locale code will be returned instead

console.log(trans('otherUnknownKeyword')); // Welcome Unknown keyword
Вход в полноэкранный режим Выйти из полноэкранного режима

Неизвестное ключевое слово

Если заданное ключевое слово не указано в текущем или запасном коде локали, то будет возвращено это ключевое слово.

import { trans } from '@mongez/localization';

console.log(trans('missingKeyword')); // will output missingKeyword as the key is missing in all our locale codes
Вход в полноэкранный режим Выйти из полноэкранного режима

Перевод из определенного кода локали

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

import { transFrom } from '@mongez/localization';

// current locale code is ar

console.log(transFrom('en', 'home')); // Home Page
Войти в полноэкранный режим Выйти из полноэкранного режима

В качестве первого аргумента мы просто передаем код локали, второй аргумент получает ключевое слово перевода.

Вложенные ключевые слова

Еще одна хорошая возможность, которую можно использовать, — группировать переводы. Этот шаблон используется в Mongez Validator, поскольку мы можем группировать ключевые слова перевода под одним ключевым словом.

import { extend, groupedTranslation } from '@mongez/localization';

// using extend
extend('en', {
  validation: {
    required: 'This field is required',
    email: 'Invalid Email Address',
  }
});

// using groupedTranslation
groupedTranslation('validator', {
  required: {
    en: 'This field is required',
  },
  email: {
    en: 'Invalid Email Address',
  }
});
Вход в полноэкранный режим Выход из полноэкранного режима

Теперь ключевое слово можно сохранить как validator.required и validator.email непосредственно в методе trans.

import { trans } from '@mongez/localization';

console.log(trans('validator.required')); // This field is required
Вход в полноэкранный режим Выход из полноэкранного режима

Динамический перевод

Это было здорово со статическими ключевыми словами, но что если мы хотим иметь перевод, который может иметь динамическое содержание, например Create new %s, где %s может быть изменен, чтобы нам не пришлось создавать десятки переводов, давайте посмотрим это в действии.

import { trans, extend } from '@mongez/localization';

extend('en', {
  createItem: 'Create new %s',
});

console.log(trans('createItem', 'User')); // Create New User
console.log(trans('createItem', 'Order')); // Create New Order
console.log(trans('createItem', 'Category')); // Create New Category
console.log(trans('createItem', 'Product')); // Create New Product
Вход в полноэкранный режим Выход из полноэкранного режима

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

Это делается под капотом с помощью Sprintf-js.

Вероятно, наиболее используемые вами заполнители — это %s для строк типа User и %d для цифр типа любого числа.

import { trans, extend } from '@mongez/localization';

extend('en', {
  orderTotal: 'Total Order: %d',
});

console.log(trans('orderTotal', 125.25)); // Total Order: 125.25


extend('en', {
  userOrderTotal: 'Total Order for %s is %d USD',
});

console.log(trans('userOrderTotal', 'Hasan', 125.25)); // Total Order for Hasan is 125.25 USD
Вход в полноэкранный режим Выход из полноэкранного режима

Не забывайте, что порядок имеет значение

Заключение

Для получения более подробной документации по пакету, не стесняйтесь посетить репозиторий Github.

В этой статье я не рассказал о других возможностях, которые можно найти в документации репозитория, таких как events обновление fallbacks и так далее.

Я начну работу над версией 2.0, в которой будут улучшены размещаемые объекты, а также поддержка JSX для размещаемых объектов.

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

Наслаждайтесь и счастливого кодинга.

Оцените статью
devanswers.ru
Добавить комментарий