Поскольку Vue.js является доступным, производительным и универсальным фреймворком для создания пользовательских веб-интерфейсов, ему также необходимо лучшее в своем классе решение для интернационализации.
Возможно, вы знаете vue-i18n, но для тех, кто уже знаком с i18next, больше подойдет адаптированная для Vue.js версия i18next.
В этом руководстве мы будем использовать модуль i18next-vue.
- TOC
- Итак, прежде всего: «Почему i18next?».
- Давайте разберемся…
- Предварительные условия
- Начало работы
- Переключатель языков
- Как получить текущий язык?
- i18next.language vs. i18next.languages vs. i18next.resolvedLanguage
- Интерполяция и плюрализация
- Форматирование
- Контекст
- Отделить переводы от кода
- Более эффективное управление переводами
- Конечно!
- Как это выглядит?
- сохранение отсутствующих переводов
- 👀 но это еще не все…
- 📦 Давайте подготовимся к производству 🚀.
- 🎉🥳 Поздравляю 🎊🎁.
- 👍
TOC
- Итак, прежде всего: «Почему i18next?».
- Давайте разберемся…
- Предварительные условия
- Начало работы
- Переключатель языков
- Как получить текущий язык?
- Интерполяция и плюрализация
- Форматирование
- Контекст
- Отделите переводы от кода
- Лучшее управление переводами
- Обязательно!
- Как это выглядит?
- сохранять недостающие переводы
- 👀 но это еще не все…
- 📦 Готовимся к производству 🚀
- 🎉🥳 Поздравляем 🎊🎁
Итак, прежде всего: «Почему i18next?».
Когда речь заходит о локализации Vue, одним из самых популярных является i18next с его Vue расширением i18next-vue, и на то есть веские причины:
i18next был создан в конце 2011 года. Это старше, чем большинство библиотек, которые вы используете сегодня, включая ваши основные фронтенд-технологии (React, Angular, Vue, …).
➡️ устойчивый
Судя по тому, как долго i18next уже доступен с открытым исходным кодом, нет ни одного реального случая i18n, который нельзя было бы решить с помощью i18next.
➡️ зрелый
i18next может быть использован в любой среде javascript (и нескольких не javascript — .net, elm, iOS, android, ruby, …), с любым фреймворком UI, с любым форматом i18n, … возможности безграничны.
➡️ расширяемость
В i18next вы получите множество функций и возможностей по сравнению с другими обычными i18n-фреймворками.
➡️ богатый
Здесь вы можете найти больше информации о том, почему i18next особенный и как он работает.
Давайте разберемся…
Предварительные условия
Убедитесь, что у вас установлен Node.js и npm. Лучше всего, если у вас есть некоторый опыт работы с простым HTML, JavaScript и базовым Vue.js, прежде чем переходить к i18next-vue.
Начало работы
Возьмите свой собственный проект Vue или создайте новый, т.е. с помощью команды vue create cli.
npx @vue/cli create vue-starter-project
Мы собираемся адаптировать приложение для определения языка в соответствии с предпочтениями пользователя.
И мы создадим переключатель языков, чтобы контент менялся между разными языками.
Давайте установим некоторые зависимости i18next:
- i18next
- i18next-vue
- i18next-browser-languagedetector
npm install i18next i18next-vue i18next-browser-languagedetector
Подготовим файл i18n.js
:
import i18next from 'i18next'
import I18NextVue from 'i18next-vue'
import LanguageDetector from 'i18next-browser-languagedetector'
i18next
// detect user language
// learn more: https://github.com/i18next/i18next-browser-languageDetector
.use(LanguageDetector)
// init i18next
// for all options read: https://www.i18next.com/overview/configuration-options
.init({
debug: true,
fallbackLng: 'en',
resources: {
en: {
translation: {
// here we will place our translations...
}
}
}
});
export default function (app) {
app.use(I18NextVue, { i18next })
return app
}
Импортируем этот файл в наш файл main.js
:
import { createApp } from 'vue'
import i18n from './i18n'
import App from './App.vue'
i18n(createApp(App)).mount('#app')
Теперь давайте попробуем перенести некоторый жестко закодированный текст в переводы.
Для первого текста мы используем простую клавишу welcome
, чтобы напрямую вызвать функцию $t
. $t
более или менее совпадает с i18next.t
.
Для второго текста мы будем использовать директиву v-html
для прямого вывода настоящего HTML.
Предупреждение о безопасности
Динамический вывод произвольного HTML на вашем сайте может быть очень опасен, так как может легко привести к XSS-уязвимостям. Используйте v-html только для доверенного содержимого и никогда для содержимого, предоставленного пользователем.
<template>
<div class="hello">
<h1>{{ $t('welcome') }}</h1>
<p v-html="$t('descr')"></p>
</div>
</template>
<script>
export default {
name: 'TranslationShowCase'
}
</script>
Тексты теперь являются частью ресурсов перевода:
import i18next from 'i18next'
import I18NextVue from 'i18next-vue'
import LanguageDetector from 'i18next-browser-languagedetector'
i18next
// detect user language
// learn more: https://github.com/i18next/i18next-browser-languageDetector
.use(LanguageDetector)
// init i18next
// for all options read: https://www.i18next.com/overview/configuration-options
.init({
debug: true,
fallbackLng: 'en',
resources: {
en: {
translation: {
welcome: 'Welcome to Your Vue.js App',
descr: 'For a guide and recipes on how to configure / customize '
+ 'this project,<br>check out the '
+ '<a href="https://cli.vuejs.org" target="_blank" '
+ 'rel="noopener">vue-cli documentation</a>.'
}
}
}
});
export default function (app) {
app.use(I18NextVue, { i18next })
return app
}
Переключатель языков
Теперь давайте определим переключатель языков:
<template>
<div class="hello">
<h1>{{ $t('welcome') }}</h1>
<p v-html="$t('descr')"></p>
<hr />
<div>
<div v-if="languages">
<span v-for="(lng, index) in Object.keys(languages)" :key="lng">
<a v-if="$i18next.resolvedLanguage !== lng" v-on:click="$i18next.changeLanguage(lng)">
{{ languages[lng].nativeName }}
</a>
<strong v-if="$i18next.resolvedLanguage === lng">
{{ languages[lng].nativeName }}
</strong>
<span v-if="index < (Object.keys(languages).length - 1)"> | </span>
</span>
</div>
</div>
</div>
</template>
<script>
export default {
name: 'TranslationShowCase',
data () {
return {
languages: {
en: { nativeName: 'English' },
de: { nativeName: 'Deutsch' }
}
}
}
}
</script>
А также добавим несколько переводов для нового языка:
import i18next from 'i18next'
import I18NextVue from 'i18next-vue'
import LanguageDetector from 'i18next-browser-languagedetector'
i18next
// detect user language
// learn more: https://github.com/i18next/i18next-browser-languageDetector
.use(LanguageDetector)
// init i18next
// for all options read: https://www.i18next.com/overview/configuration-options
.init({
debug: true,
fallbackLng: 'en',
resources: {
en: {
translation: {
welcome: 'Welcome to Your Vue.js App',
descr: 'For a guide and recipes on how to configure / customize '
+ 'this project,<br>check out the '
+ '<a href="https://cli.vuejs.org" target="_blank" '
+ 'rel="noopener">vue-cli documentation</a>.'
}
},
de: {
translation: {
welcome: 'Willkommen zu Deiner Vue.js App',
descr: 'Eine Anleitung und Rezepte zum Konfigurieren/Anpassen '
+ 'dieses Projekts findest du<br>in der '
+ '<a href="https://cli.vuejs.org" target="_blank" '
+ 'rel="noopener">vue-cli-Dokumentation</a>.'
}
}
}
});
export default function (app) {
app.use(I18NextVue, { i18next })
return app
}
🥳 Потрясающе, вы только что создали свой первый переключатель языков!
Благодаря i18next-browser-languagedetector теперь он пытается определить язык браузера и автоматически использовать этот язык, если вы предоставили для него переводы. Выбранный вручную язык в переключателе языков сохраняется в localStorage, и при следующем посещении страницы этот язык будет использоваться как предпочтительный.
Как получить текущий язык?
Начиная с i18next v21 существует i18next.resolvedLanguage
.
Он устанавливается на текущий разрешенный язык и может использоваться как основной используемый язык, например, в переключателе языков.
Если ваш обнаруженный язык, например, en-US
, а вы предоставили перевод только для en
(fallbackLng), вместо i18next.resolvedLanguage
вернется en
.
i18next.language vs. i18next.languages vs. i18next.resolvedLanguage
/* language */
i18next.language;
// Is set to the current detected or set language.
/* language */
i18next.languages;
// Is set to an array of language codes that will be used to look up the translation value.
// When the language is set, this array is populated with the new language codes.
// Unless overridden, this array is populated with less-specific versions of that code for fallback purposes, followed by the list of fallback languages
// initialize with fallback languages
i18next.init({
fallbackLng: ["es", "fr", "en-US", "dev"]
});
// change the language
i18next.changeLanguage("en-US-xx");
// new language and its more generic forms, followed by fallbacks
i18next.languages; // ["en-US-xx", "en-US", "en", "es", "fr", "dev"]
// change the language again
i18next.changeLanguage("de-DE");
// previous language is not retained
i18next.languages; // ["de-DE", "de", "es", "fr", "en-US", "dev"]
/* resolvedLanguage */
i18next.resolvedLanguage;
// Is set to the current resolved language.
// It can be used as primary used language,
// for example in a language switcher.
Интерполяция и плюрализация
i18next не ограничивается предоставлением стандартных функций i18n.
Но, безусловно, он способен обрабатывать множественное число и интерполяцию.
Если вы хотите узнать, как это работает, посмотрите этот раздел в другой статье блога.
Форматирование
Также можно выполнять форматирование.
Если вы хотите узнать, как это работает, посмотрите этот раздел в другой статье блога.
Контекст
Как насчет специфического приветствия, основанного на текущем времени суток, т.е. утро, вечер и т.д.
Это возможно благодаря контекстной функции i18next.
Если вы хотите посмотреть, как это работает, загляните в этот раздел в другой статье блога.
Отделить переводы от кода
Наличие переводов в нашем файле i18n.js
работает, но не очень удобно для работы переводчиков.
Давайте отделим переводы от кода и поместим их в специальные json-файлы.
Поскольку это веб-приложение, нам поможет i18next-http-backend.
npm install i18next-http-backend
Переместите переводы в общую папку:
Адаптируйте файл i18n.js
для использования i18next-http-backend
:
import i18next from 'i18next'
import I18NextVue from 'i18next-vue'
import LanguageDetector from 'i18next-browser-languagedetector'
import Backend from 'i18next-http-backend'
i18next
// i18next-http-backend
// loads translations from your server
// https://github.com/i18next/i18next-http-backend
.use(Backend)
// detect user language
// learn more: https://github.com/i18next/i18next-browser-languageDetector
.use(LanguageDetector)
// init i18next
// for all options read: https://www.i18next.com/overview/configuration-options
.init({
debug: true,
fallbackLng: 'en'
});
export default function (app) {
app.use(I18NextVue, { i18next })
return app
}
Теперь переводы загружаются асинхронно.
Если у вас медленное подключение к сети, вы можете заметить, что пока переводы не загружены, отображаются только ключи i18n.
Чтобы предотвратить это, мы используем новую функциональность Suspense в Vue.js.
Сначала адаптируем файл i18n.js
, экспортировав обещание i18next init:
import i18next from 'i18next'
import I18NextVue from 'i18next-vue'
import LanguageDetector from 'i18next-browser-languagedetector'
import Backend from 'i18next-http-backend'
export const
i18nextPromise = i18next
// i18next-http-backend
// loads translations from your server
// https://github.com/i18next/i18next-http-backend
.use(Backend)
// detect user language
// learn more: https://github.com/i18next/i18next-browser-languageDetector
.use(LanguageDetector)
// init i18next
// for all options read: https://www.i18next.com/overview/configuration-options
.init({
debug: true,
fallbackLng: 'en'
});
export default function (app) {
app.use(I18NextVue, { i18next })
return app
}
…и используем это обещание в App.vue
:
<template>
<img alt="Vue logo" src="./assets/logo.png">
<TranslationShowCase />
</template>
<script>
import TranslationShowCase from './components/TranslationShowCase.vue'
import { i18nextPromise } from './i18n.js'
export default {
name: 'App',
components: {
TranslationShowCase
},
// used in combination with Suspense.
// useful when translations are not in-memory...
async setup() {
await i18nextPromise
return {}
}
}
</script>
Давайте создадим новый файл: Suspenser.vue
:
<template>
<Suspense>
<template #default>
<App />
</template>
<template #fallback>
<div>
<img alt="Vue logo" src="./assets/logo.png">
<h1>Loading...</h1>
</div>
</template>
</Suspense>
</template>
<script>
import App from './App.vue'
export default {
name: 'Suspenser',
components: {
App
}
}
</script>
И используем его в вашем файле main.js
:
import { createApp } from 'vue'
import i18n from './i18n'
import App from './Suspenser.vue'
i18n(createApp(App)).mount('#app')
Теперь, пока ваши переводы загружаются, вы будете видеть шаблон отката:
Теперь ваше приложение выглядит все так же, но ваши переводы разделены.
Если вы хотите поддерживать новый язык, просто создайте новую папку и новый json-файл перевода.
Это дает вам возможность отправить переводы нескольким переводчикам.
Или, если вы работаете с системой управления переводами, вы можете просто синхронизировать файлы с помощью cli.
Более эффективное управление переводами
Отправляя переводы некоторым переводчикам или бюро переводов, вы получаете больше контроля и прямой контакт с ними. Но это также означает больше работы для вас.
Это традиционный способ. Но имейте в виду, что пересылка файлов всегда сопряжена с накладными расходами.
Существует ли лучший вариант?
Конечно!
i18next помогает перевести приложение, и это здорово, но есть и другие варианты.
- Как вы интегрируете любые переводческие службы/агентства?
- Как вы отслеживаете новый или удаленный контент?
- Как вы обеспечиваете надлежащее версионирование?
- Как развернуть изменения в переводе без развертывания всего приложения?
- и многое другое…
Ищу что-то подобное❓
- Легко интегрировать
- Непрерывное развертывание? Непрерывная локализация!
- Легко управляйте файлами переводов
- Заказывайте профессиональные переводы
- Аналитика и статистика
- Получите выгоду от нашей сети доставки контента (CDN)
- Версионирование ваших переводов
- Автоматический и машинный перевод по требованию
- Без риска: Возьмите свои данные с собой
- Прозрачное и справедливое ценообразование
- и многое другое…
Как это выглядит?
Сначала вам нужно зарегистрироваться на сайте locize и войти в систему.
Затем создайте новый проект в locize и добавьте свои переводы. Вы можете добавить свои переводы либо с помощью cli, либо импортировав отдельные json-файлы, либо через API.
Выполнив это, мы заменим i18next-http-backend на i18next-locize-backend.
npm install i18next-locize-backend
После импорта переводов в locize удалите папку locales.
Адаптируйте файл i18n.js
для использования i18next-locize-backend
и убедитесь, что вы скопировали project-id и api-key из вашего проекта locize:
import I18NextVue from 'i18next-vue'
import i18next from 'i18next'
import Backend from 'i18next-locize-backend'
import LanguageDetector from 'i18next-browser-languagedetector'
const locizeOptions = {
projectId: '94c21299-0cf5-4ad3-92eb-91f36fc3f20f',
apiKey: 'bc8586d9-fceb-489c-86ac-2985393ed955', // YOU should not expose your apps API key to production!!!
version: 'latest'
}
export const
i18nextPromise = i18next
// i18next-locize-backend
// loads translations from your project, saves new keys to it (saveMissing: true)
// https://github.com/locize/i18next-locize-backend
.use(Backend)
// detect user language
// learn more: https://github.com/i18next/i18next-browser-languageDetector
.use(LanguageDetector)
// init i18next
// for all options read: https://www.i18next.com/overview/configuration-options
.init({
debug: true,
fallbackLng: 'en',
backend: locizeOptions
})
export default function (app) {
app.use(I18NextVue, { i18next })
return app
}
i18next-locize-backend предлагает функциональность для получения доступных языков непосредственно из locize, давайте воспользуемся ею:
<template>
<div class="hello">
<h1>{{ $t('welcome') }}</h1>
<p v-html="$t('descr')"></p>
<i>{{ $t('new.key', 'this will be added automatically') }}</i>
<hr />
<div>
<div v-if="languages">
<span v-for="(lng, index) in Object.keys(languages)" :key="lng">
<a v-if="$i18next.resolvedLanguage !== lng" v-on:click="$i18next.changeLanguage(lng)">
{{ languages[lng].nativeName }}
</a>
<strong v-if="$i18next.resolvedLanguage === lng">
{{ languages[lng].nativeName }}
</strong>
<span v-if="index < (Object.keys(languages).length - 1)"> | </span>
</span>
</div>
</div>
</div>
</template>
<script>
import i18next from 'i18next'
export default {
name: 'TranslationShowCase',
data () {
return {
languages: []
}
},
async mounted () {
this.languages = await i18next.services.backendConnector.backend.getLanguages()
}
}
</script>
сохранение отсутствующих переводов
Благодаря использованию функциональности saveMissing, новые ключи добавляются в locize автоматически, в процессе разработки приложения.
Просто передайте saveMissing: true
в опциях i18next:
import I18NextVue from 'i18next-vue'
import i18next from 'i18next'
import Backend from 'i18next-locize-backend'
import LanguageDetector from 'i18next-browser-languagedetector'
const locizeOptions = {
projectId: '94c21299-0cf5-4ad3-92eb-91f36fc3f20f',
apiKey: 'bc8586d9-fceb-489c-86ac-2985393ed955', // YOU should not expose your apps API key to production!!!
version: 'latest'
}
export const
i18nextPromise = i18next
// i18next-locize-backend
// loads translations from your project, saves new keys to it (saveMissing: true)
// https://github.com/locize/i18next-locize-backend
.use(Backend)
// detect user language
// learn more: https://github.com/i18next/i18next-browser-languageDetector
.use(LanguageDetector)
// init i18next
// for all options read: https://www.i18next.com/overview/configuration-options
.init({
debug: true,
fallbackLng: 'en',
backend: locizeOptions,
saveMissing: true
})
export default function (app) {
app.use(I18NextVue, { i18next })
return app
}
Каждый раз, когда вы будете использовать новую клавишу, она будет отправляться в locize, т.е:
<i>{{ $t('new.key', 'this will be added automatically') }}</i>
приведет к тому, что locize будет выглядеть следующим образом:
👀 но это еще не все…
Благодаря плагину locize-lastused, вы сможете найти и отфильтровать в locize, какие клавиши используются или не используются больше.
С помощью плагина locize вы сможете использовать ваше приложение в редакторе locize InContext Editor.
Наконец, с помощью рабочего процесса автоматического машинного перевода и использования функции saveMissing новые ключи не только автоматически добавляются в locize в процессе разработки приложения, но и автоматически переводятся на целевые языки с помощью машинного перевода.
Посмотрите это видео, чтобы увидеть, как выглядит рабочий процесс автоматического машинного перевода!
npm install locize-lastused locize
используйте их в i18n.js
:
import I18NextVue from 'i18next-vue'
import i18next from 'i18next'
import Backend from 'i18next-locize-backend'
import LanguageDetector from 'i18next-browser-languagedetector'
import LastUsed from 'locize-lastused'
import { locizePlugin } from 'locize'
const locizeOptions = {
projectId: '94c21299-0cf5-4ad3-92eb-91f36fc3f20f',
apiKey: 'bc8586d9-fceb-489c-86ac-2985393ed955', // YOU should not expose your apps API key to production!!!
version: 'latest'
}
export const
i18nextPromise = i18next
// locize-lastused
// sets a timestamp of last access on every translation segment on locize
// -> safely remove the ones not being touched for weeks/months
// https://github.com/locize/locize-lastused
.use(LastUsed)
// locize-editor
// InContext Editor of locize
.use(locizePlugin)
// i18next-locize-backend
// loads translations from your project, saves new keys to it (saveMissing: true)
// https://github.com/locize/i18next-locize-backend
.use(Backend)
// detect user language
// learn more: https://github.com/i18next/i18next-browser-languageDetector
.use(LanguageDetector)
// init i18next
// for all options read: https://www.i18next.com/overview/configuration-options
.init({
debug: true,
fallbackLng: 'en',
saveMissing: true,
backend: locizeOptions,
locizeLastUsed: locizeOptions
})
export default function (app) {
app.use(I18NextVue, { i18next })
return app
}
Автоматический машинный перевод:
Фильтр последних использованных переводов:
InContext Editor:
📦 Давайте подготовимся к производству 🚀.
Теперь мы подготовим приложение к запуску в производство.
Сначала в locize создайте выделенную версию для производства. Не включайте автоматическую публикацию для этой версии, а публикуйте вручную или через API или через CLI.
И наконец, включите Cache-Control max-age для этой производственной версии.
Давайте воспользуемся функцией окружения в react-scripts.
Создадим файл окружения по умолчанию, один для разработки и один для производства:
.env
:
VUE_APP_LOCIZE_PROJECTID=94c21299-0cf5-4ad3-92eb-91f36fc3f20f
.env.development
:
VUE_APP_LOCIZE_VERSION=latest
VUE_APP_LOCIZE_APIKEY=bc8586d9-fceb-489c-86ac-2985393ed955
.env.production
:
VUE_APP_LOCIZE_VERSION=production
Теперь давайте адаптируем файл i18n.js:
import I18NextVue from 'i18next-vue'
import i18next from 'i18next'
import Backend from 'i18next-locize-backend'
import LanguageDetector from 'i18next-browser-languagedetector'
import LastUsed from 'locize-lastused'
import { locizePlugin } from 'locize'
const isProduction = process.env.NODE_ENV === 'production'
const locizeOptions = {
projectId: process.env.VUE_APP_LOCIZE_PROJECTID,
apiKey: process.env.VUE_APP_LOCIZE_APIKEY, // YOU should not expose your apps API key to production!!!
version: process.env.VUE_APP_LOCIZE_VERSION
}
if (!isProduction) {
// locize-lastused
// sets a timestamp of last access on every translation segment on locize
// -> safely remove the ones not being touched for weeks/months
// https://github.com/locize/locize-lastused
i18next.use(LastUsed);
}
export const
i18nextPromise = i18next
// locize-editor
// InContext Editor of locize
.use(locizePlugin)
// i18next-locize-backend
// loads translations from your project, saves new keys to it (saveMissing: true)
// https://github.com/locize/i18next-locize-backend
.use(Backend)
// detect user language
// learn more: https://github.com/i18next/i18next-browser-languageDetector
.use(LanguageDetector)
// init i18next
// for all options read: https://www.i18next.com/overview/configuration-options
.init({
debug: !isProduction,
fallbackLng: 'en',
saveMissing: !isProduction,
backend: locizeOptions,
locizeLastUsed: locizeOptions
})
export default function (app) {
app.use(I18NextVue, { i18next })
return app
}
Теперь, во время разработки, вы будете продолжать сохранять отсутствующие ключи и использовать функцию lastused. => npm run serve
А в производственной среде функции saveMissing и lastused отключены, а также api-ключ не раскрыт. => npm run build
Кэширование:
Слияние версий:
🧑💻 Полный код можно найти здесь.
Посмотрите также часть интеграции кода в этом видео на YouTube.
🎉🥳 Поздравляю 🎊🎁.
Надеюсь, вы узнали несколько новых вещей о i18next, локализации Vue.js и современных рабочих процессах локализации.
Итак, если вы хотите вывести свою тему i18n на новый уровень, стоит попробовать платформу управления локализацией — locize.
Основатели locize также являются создателями i18next. Таким образом, используя locize, вы напрямую поддерживаете будущее i18next.
👍