Как локализовать ваше приложение с помощью jQuery.I18n

За последний месяц я написал несколько статей об интернационализации, посвященных использованию I18n в приложениях Rails, а также различным решениям для JavaScript . Сегодняшний гость — библиотека jQuery.I18n, кратко освещенная в одном из предыдущих постов. Это решение поддерживает пол, грамматические формы, динамическое изменение языка, резервные цепочки и многое другое.

Мы собираемся подробно обсудить возможности jQuery.I18n, а также увидеть его в действии, создав демонстрационное приложение JavaScript. Вот краткий обзор тем, которые мы рассмотрим:

• Основная информация о jQuery.I18n.
• Настройка демо-приложения и загрузка необходимых файлов.
• Процесс создания файлов перевода.
• Загрузка файлов перевода и некоторые ошибки, которые необходимо учитывать.
• Переключение локали.
• Сохранение данных локали с использованием History API.
• Отображение локализованных сообщений на основе data-атрибутов HTML5 .
• Отображение локализованных сообщений с использованием пользовательского кода JavaScript.
• Использование пола и информации о плюрализме в переводах.
• Оптимизация кода, чтобы избежать повторения.
• Добавляем «волшебные» слова.
• Документирование ваших переводов.

Исходный код этой статьи доступен на GitHub .

Краткое примечание о демо-приложении

Чтобы увидеть конечный результат в действии, вам нужно настроить веб-сервер. Я собираюсь использовать Microsoft IIS , но есть множество других доступных решений, которые помогут вам начать работу за минуту:

• MAMP .
• WAMP .
• И другие.

О jQuery.I18n

Конечно, вы знаете, что такое Википедия , и, вероятно, использовали этот веб-сайт много раз, так как он знает все, начиная от физики и химии до популярных (и менее популярных) фильмов и компьютерных игр. Wikipedia поддерживается компанией под названием Wikimedia Foundation, которая также занимается такими проектами, как Wikinews , Wikivoyage и многими другими. Все эти проекты доступны по всему миру и доступны на разных языках, поэтому интернационализация абсолютно необходима для Викимедиа.

Поэтому эта компания создала популярное решение на основе jQuery для интернационализации приложений JavaScript и назвала его просто jQuery.I18n. Не очень причудливое имя, но поверьте мне, это больше, чем кажется на первый взгляд. Эта библиотека действительно удобна и мощна, поэтому давайте не будем тратить наше время и обсудим ее особенности сейчас. Чтобы сделать наше путешествие более интересным и полезным, мы собираемся применить изученные концепции на практике.

Файлы перевода

jQuery.I18n хранит переводы в простых файлах JSON. Если вы, как и я, фанат Rails, вы обнаружите, что этот процесс очень похож на хранение переводов в файлах YAML.

Фактические переводы в формате ключ-значение, например

{ "title": "Example Application" }

titleэто, конечно, ключ, тогда как Example Applicationэто его значение. Рекомендуется называть ключи строчными буквами, разделив их словами -. Документация jQuery.I18n также предлагает добавить к ключам префикс имени приложения:

{ "myapp-title": "Example Application" }

… но это не обязательно.

Помимо переводов, файлы могут содержать метаданные, такие как информация об авторах, дате последнего обновления и т. Д. Метаданные имеют свой собственный ключ, начинающийся с @:

{
"@metadata": {
    "authors": [
        "Alice",
        "David"
    ],
    "last-updated": "2016-10-25",
    "locale": "en"
},
"title": "Example Application"
}

"en": {
"title": "Example Application"
},
"ru": {
title: "Тестовое приложение"
}

"en": {
"title": "Example Application"
},
"ru": "ru/ru.json"

{
  "@metadata": {
    "authors": [
      "Ilya"
    ],
    "last-updated": "2016-10-25",
    "locale": "en"
  },
  "app-title": "Example Application"
}

{
  "@metadata": {
    "authors": [
      "Ilya"
    ],
    "last-updated": "2016-10-25",
    "locale": "ru"
  },
  "app-title": "Тестовое приложение"
}

$ git clone https://github.com/wikimedia/jquery.i18n.git
$ cd jquery.i18n
$ git submodule update --init

|-- js
|-- global.js
|-- i18n
|-- en.json
|-- ru.json
|-- lib
|-- CLDRPluralRuleParser
|-- CLDRPluralRuleParser.js
|-- jquery.i18n
|-- jquery.i18n.js
|-- jquery.i18n.language.js
|-- ...other files here

<!DOCTYPE>
<html>
<head>
  <meta charset="utf-8">
  <title>Demo Application</title>
  <script src="https://code.jquery.com/jquery-3.1.1.min.js"></script>

  <script src="js/lib/CLDRPluralRuleParser/CLDRPluralRuleParser.js"></script>
  <script src="js/lib/jquery.i18n/jquery.i18n.js"></script>
  <script src="js/lib/jquery.i18n/jquery.i18n.messagestore.js"></script>
  <script src="js/lib/jquery.i18n/jquery.i18n.fallbacks.js"></script>
  <script src="js/lib/jquery.i18n/jquery.i18n.language.js"></script>
  <script src="js/lib/jquery.i18n/jquery.i18n.parser.js"></script>
  <script src="js/lib/jquery.i18n/jquery.i18n.emitter.js"></script>
  <script src="js/lib/jquery.i18n/jquery.i18n.emitter.bidi.js"></script>

  <script src="js/global.js"></script>
</head>
<body>
</body>
</html>

$.i18n().load( {
'en': {
  'app-title': 'Example Application'
}
} );

$.i18n().load({
'app-title': 'Example Application'
}, 'en');

$.i18n().load( {
'en': 'dir/en.json'
} );

$.i18n().load( {
'en': {
  'app-title': 'Example Application'
}
} );

// ... some instructions

$.i18n().load( {
'en': {
  'another key': 'a value'
}
} );

jQuery(function($) {
  $.i18n().load( {
    'en': './js/i18n/en.json',
    'ru': './js/i18n/ru.json'
  } );
});

  $.i18n().load( {
    'en': 'i18n/en.json',
    'ru': 'i18n/ru.json'
  } ).done( function() { console.log('done!') } );

$.i18n( {
    locale: 'en'
} );

<html lang="en" dir="ltr">

$.i18n().locale = 'ru';

<ul class="switch-locale">
  <li><a href="#" data-locale="en">English</a></li>
  <li><a href="#" data-locale="ru">Русский</a></li>
</ul>

jQuery(function($) {
// ...
  $.i18n().load( {
    'en': './js/i18n/en.json',
    'ru': './js/i18n/ru.json'
  } ).done(function() {
  $('.switch-locale').on('click', 'a', function(e) {
    e.preventDefault();
    $.i18n().locale = $(this).data('locale');
  });
});
});

<!-- ... -->
  <script src="js/lib/history/jquery.history.js"></script>
  <script src="js/lib/url/url.min.js"></script>
  <script src="js/global.js"></script>
<!-- ... -->

var set_locale_to = function(locale) {
  if (locale)
    $.i18n().locale = locale;
};

jQuery(function() {
  $.i18n().load( {
// ...
  } ).done(function() {
    set_locale_to(url('?locale'));
// ...
});
});

jQuery(function() {
  $.i18n().load( {
// ...
  } ).done(function() {
    set_locale_to(url('?locale'));
History.Adapter.bind(window, 'statechange', function(){
  set_locale_to(url('?locale'));
});
// ...
});
});

var set_locale_to = function(locale) {
  if (locale)
    $.i18n().locale = locale;
};

jQuery(function() {
  $.i18n().load( {
    'en': './js/i18n/en.json',
    'ru': './js/i18n/ru.json'
  } ).done(function() {
    set_locale_to(url('?locale'));

    History.Adapter.bind(window, 'statechange', function(){
      set_locale_to(url('?locale'));
    });

    $('.switch-locale').on('click', 'a', function(e) {
      e.preventDefault();
      History.pushState(null, null, "?locale=" + $(this).data('locale'));
    });
  });
});

<h1 data-i18n="app-title"></h1>

var set_locale_to = function(locale) {
  if (locale) {
    $.i18n().locale = locale;
  }
  $('body').i18n();
};
// ...

<h1 data-i18n="app-title">Example Application</h1>

$.i18n('some-key');

<body>
<!-- ... -->
<h2 id="welcome">Welcome</h2>
</body>

"welcome": "Welcome!"

"welcome": "Добро пожаловать!"

var set_locale_to = function(locale) {
// ...
$('#welcome').text($.i18n('welcome'));
};

"welcome": "Welcome, $1!"

"welcome": "Добро пожаловать, $1!"

var set_locale_to = function(locale) {
// ...
$('#welcome').text($.i18n('welcome', 'John'));
};

<!-- ... -->
<div id="letter-1">
  <p><em></em></p>
  <p>letter's text...</p>
</div>

<div id="letter-2">
  <p><em></em></p>
  <p>letter's text...</p>
</div>

"letter": "A letter from $1! {{GENDER:$2|He|She}} says:"

"letter": "Письмо от $1! {{GENDER:$2|Он|Она}} говорит:"

var set_locale_to = function(locale) {
// ...
  $('#letter-1').find('p > em').text($.i18n('letter', 'Ann', 'female'));
  $('#letter-2').find('p > em').text($.i18n('letter', 'Rick', 'male'));
}

<p id="letters"></p>

"letters": "You have $1 {{PLURAL:$1|letter|letters}}"

"letters": "У вас $1 {{PLURAL:$1|письмо|писем|письма}}"

var set_locale_to = function(locale) {
// ...
$('#letters').text($.i18n('letters', 5));
};

<!-- ... -->
<h1 class="translate" data-args="app-title">Example Application</h1>
<h2 class="translate" data-args="welcome,John">Welcome</h2>

<p class="translate" data-args="letters,5"></p>

<div>
  <p><em class="translate" data-args="letter,Ann,female"></em></p>
  <p>letter's text...</p>
</div>

<div>
  <p><em class="translate" data-args="letter,Rick,male"></em></p>
  <p>letter's text...</p>
</div>

var set_locale_to = function(locale) {
// ...
  $('.translate').each(function() {
    var args = [], $this = $(this);
    if ($this.data('args'))
      args = $this.data('args').split(',');
    $this.html( $.i18n.apply(null, args) );
};

jQuery(function() {
  $.extend($.i18n.parser.emitter, {
    sitename: function() {
      return "Demo";
    }
});
});

"copyright": "{{SITENAME}}. All rights reserved."

"copyright": "{{SITENAME}}. All rights reserved."

<!-- ... -->
<footer class="translate" data-args="copyright"></footer>

// ...
  $.extend($.i18n.parser.emitter, {
    sitename: function() {
      return "Demo";
    },
    link: function (nodes) {
      return '<a href="' + nodes[1] + '">' + nodes[0] + '</a>';
    }
  } );

"about": "{{link:About {{SITENAME}}|localhost/about?locale=en}}"

"about": "{{link:{{SITENAME}}|localhost/about?locale=ru}}"

{
  "@metadata": {
    "authors": [
      "Ilya"
    ]
  },
  "app-title": "App's title",
  "welcome": "Welcoming message. Should be friendly.",
  "letter": "Notification about letter from someone. Should be informal.",
  "letters": "Total letters count.",
  "copyright": "The name of the site (transliterated) and copyrights.",
  "about": "Link to About Us page. The URL should contain the proper locale."
}