From 10c40e7f75545a84bb14a539310b8efa94c75770 Mon Sep 17 00:00:00 2001 From: Inna Belaya Date: Mon, 5 Oct 2015 15:35:29 +0300 Subject: [PATCH] fix after review --- README.md | 111 +++++++++++++++++++++++++++++------------------------- api.ru.md | 24 ++++++------ 2 files changed, 73 insertions(+), 62 deletions(-) diff --git a/README.md b/README.md index c763445..6efe99a 100644 --- a/README.md +++ b/README.md @@ -7,15 +7,15 @@ enb-bem-i18n [![Coverage Status](https://img.shields.io/coveralls/enb-bem/enb-bem-i18n.svg?style=flat)](https://coveralls.io/r/enb-bem/enb-bem-i18n?branch=master) [![devDependency Status](https://img.shields.io/david/enb-bem/enb-bem-i18n.svg?style=flat)](https://david-dm.org/enb-bem/enb-bem-i18n) -Пакет предоставляет набор ENB-технологий для сборки файлов, обеспечивающих мультиязыковую поддержку проектов, созданных по [БЭМ-методологии](https://ru.bem.info/method/). Под мультиязыковой поддержкой понимается интернационализация (далее по тектсу также i18n). +Пакет предоставляет набор ENB-технологий для сборки файлов, обеспечивающих мультиязыковую поддержку БЭМ-проектов. Под мультиязыковой поддержкой понимается интернационализация (далее по тексту также i18n). -С помощью технологий пакета `enb-bem-i18n` осуществляется сборка модуля для интернационализации (`i18n`). +С помощью технологий пакета `enb-bem-i18n` осуществляется сборка модуля для интернационализации (`i18n`) вашего проекта. **Технологии пакета `enb-bem-i18n`:** * [keysets](/api.ru.md#keysets) — служебная технология для сборки исходных файлов с переводами. -* [i18n](/api.ru.md#i18n) — технология для формирования бандлов с переводами для каждого языка, которые будут использоваться в дальнейшем. -* [keysets-xml](/api.ru.md#keysets-xml) — технология для локализации сервисов, использующих XSLT для шаблонизации. +* [i18n](/api.ru.md#i18n) — технология для формирования бандлов с переводами для каждого языка. +* [keysets-xml](/api.ru.md#keysets-xml) — технология для локализации сервисов, использующих шаблонизатор XSLT. Принципы работы технологий и их API описаны в документе [API технологий](/api.ru.md). @@ -24,7 +24,7 @@ enb-bem-i18n * [bem-bl](https://ru.bem.info/libs/bem-bl/dev/) * [bem-core](https://ru.bem.info/libs/bem-core/) ->Особенности реализации для каждой библиотеки описаны в разделе [подключение библиотек](#Поддержка-библиотек). +>Особенности реализации для каждой библиотеки описаны в разделе [Различия в использовании `i18n` в `bem-bl` и `bem-core`](#Различия-в-использовании-i18n-в-bem-bl-и-bem-core). ## Установка @@ -33,17 +33,18 @@ enb-bem-i18n npm install --save-dev enb-bem-i18n ``` -**Требования:** зависимость от пакета `enb` версии `0.11.0` или выше. +**Требования:** пакет `enb` версии `0.11.0` или выше. ## Обзор документа - [Быстрый старт](#Быстрый-старт) +- [Принцип работы пакета `enb-bem-i18n`](#Принцип-работы-пакета-enb-bem-i18n) - [Основные понятия](#Основные-понятия) - [Исходные данные — keysets](#Исходные-данные--keysets) - [Расположение в файловой системе](#Расположение-в-файловой-системе) - [Ядро `i18n`](#Ядро-i18n) -- [Работа с технологиями](#Работа-с-технологиями) +- [Описание работы с технологиями](#Описание-работы-с-технологиями) - [Объединение данных](#Объединение-данных) - [Обработка данных](#Обработка-данных) - [Сборка шаблонов](#Сборка-шаблонов) @@ -57,9 +58,9 @@ npm install --save-dev enb-bem-i18n - [BH](#bh) - [API `i18n`](#api-i18n) - [Инициализация](#Инициализация) - - [Параметризация значений](#Параметризация-значений) -- [Отличия в работе](#Отличия-в-работе) - - [Переключение между языками во время исполнения](#Переключение-между-языками-во-время-исполнения) + - [Передаваемые параметры функции `i18n`](#Передаваемые-параметры-функции-i18n) +- [Различия в использовании `i18n` в `bem-bl` и `bem-core`](#Различия-в-использовании-i18n-в-bem-bl-и-bem-core) + - [Переключение между языками в runtime](#Переключение-между-языками-в-runtime) - [Хранение общих keysets-файлов с переводами](#Хранение-общих-keysets-файлов-с-переводами) - [Расположение ядра `i18n`](#Расположение-ядра-i18n) @@ -67,7 +68,7 @@ npm install --save-dev enb-bem-i18n ## Быстрый старт -Чтобы собрать файлы интернализации для каждого языка, подключите необходимые технологии: +Чтобы собрать файлы интернационализации для каждого языка, подключите необходимые технологии в конфигурационном файле сборщика: ```js var I18NTech = require('enb-bem-i18n/techs/i18n'), @@ -96,6 +97,13 @@ module.exports = function(config) { }); }; ``` + +## Принцип работы пакета `enb-bem-i18n` + +В основе работы пакета `enb-bem-i18n` лежит библиотека для интернационализации — [ядро `i18n`](#Ядро-i18n). Изначально ядро не содержит данных с переводами, оно наполняется данными ([инициализируется](#Инициализация)) из [keysets](#Исходные-данные-keysets)-файлов. + +Результатом работы технологии [i18n](/api.ru.md#i18n) является [функция `i18n`](#Обработка данных), которая общается с ядром и позволяет получить конкретное значение (строку) для указанного языка. Функция `i18n` может вызываться из [шаблонов](#В-шаблонах) или [клиентского JavaScript-кода](#В-javascript). + ## Основные понятия ### Исходные данные — keysets @@ -119,15 +127,6 @@ module.exports = function(config) { Набор данных `ключ: 'значение'` передается с указанием контекста (`scope`). Обычно контекстом служит имя блока. -Пример keysets-файла: - -```js -module.exports = { - scope: { - key: 'val' - } -}; -``` Пример keysets-файла для русского языка: ```js @@ -158,28 +157,28 @@ block/ * В `bem-bl` — в файл `all.js`. * В `bem-core` — в файл `.i18n.js`. -Файлы `all.js` и `.i18n.js` Может содержать [ядро `i18n`](#Ядро-i18n) для библиотеки `bem-bl` и `bem-core`, соответственно. - ``` common.blocks/ block1/ block1.css block1.js block1.i18n.js # Исходный файл с переводом, содержащий - # общие переводы для всех языков. + # общие переводы. # Может содержать ядро `i18n` для библиотеки ` bem-core`. block1.i18n/ # Директория для хранения файлов с переводами для разных языков. en.js ru.js - all.js # Исходный файл с переводом, содержащий - # общие переводы (в данном случае для + all.js # Исходный файл с переводом (для # русского и английского языков). # Может содержать ядро `i18n` для библиотеки `bem-bl`. ``` ### Ядро `i18n` -Ядро `i18n` — это библиотека для интернационализации. Ядро находится в keysets-файлах (`.i18n.js` или `.all.js`) в одной из базовых библиотек блоков. +Ядро `i18n` — это библиотека для интернационализации. Ядро находится в keysets-файлах (`.i18n.js` или `.all.js`) в одной из базовых библиотек блоков: + +* В `bem-bl` — файл `all.js`. +* В `bem-core` — файл `.i18n.js`. Пакет `enb-bem-i18n` поддерживает разные реализации ядра интернационализации для библиотек `bem-bl` и `bem-core`. @@ -215,9 +214,9 @@ common.blocks/ } } ``` -Перед использованием ядро должно быть инициализировано данными из keysets-файлов. +Перед использованием ядро должно быть [инициализировано](#Инициализация) данными из keysets-файлов. -**Важно!** Для получения ядра необходимо добавить `mustDeps`-зависимость блокам, которые используют i18n. +**Важно!** Для получения ядра необходимо добавить [mustDeps](https://ru.bem.info/technology/deps/about/)-зависимость блокам, которые используют i18n. * Для bem-bl: @@ -237,12 +236,16 @@ common.blocks/ >Подробно про API использования ядра `i18n` читайте в разделе [API `i18n`](#api-i18n). -## Работа с технологиями +>Примеры всех вариантов использования ядра рассмотрены в [тестах к технологии](https://github.com/enb-bem/enb-bem-i18n/blob/master/test/techs/i18n-merge-keysets.test.js). + +## Описание работы с технологиями Данные из keysets-файлов `.js` во время сборки проходят несколько этапов: * [Объединение данных исходных файлов в один для указанного языка](#Объединение-данных) * [Обработка данных из объединенного файла](#Обработка-данных) +* [Сборка шаблонов](#Сборка шаблонов) +* [Сборка только необходимых переводов](#Сборка-только-необходимых-переводов) ### Объединение данных @@ -289,14 +292,12 @@ module.exports = { }; ``` ->Примеры всех вариантов использования ядра рассмотрены в [тестах к технологии](https://github.com/enb-bem/enb-bem-i18n/blob/master/test/techs/i18n-merge-keysets.test.js). - ### Обработка данных Данные из объединенного файла `?.keysets..js` обрабатываются технологией [i18n](/api.ru.md#i18n). Результатом работы является функция `i18n`, которая при вызове из [шаблонов](#В-шаблонах) или [клиентского JavaScript](#В-javascript) принимает ключ и отдает значение (строку) для конкретного языка. >API взаимодействия с ядром `i18n` описан в разделе [API `i18n`](#api-i18n). -Результатом являются `lang..js`-файлы, содержащие строки переводов, соответствующие запрошенным ключам. +В результате работы технологии [i18n](/api.ru.md#i18n) являются `lang..js`-файлы, содержащие строки переводов, соответствующие запрошенным ключам. ### Сборка шаблонов @@ -311,11 +312,14 @@ index.en.bemhtml.js # index.lang.en.js + index.bemhtml.js index.ru.bemhtml.js # index.lang.ru.js + index.bemhtml.js ``` -После подключения `BEM.I18N` как сторонней библиотеки ее можно использовать в BEMHTML-шаблонах с помощью метода `this.require()`, а в BH из пространства имён `bh.lib`. +После подключения `BEM.I18N` как сторонней библиотеки ее можно использовать: + +* в BEMHTML-шаблонах с помощью метода `this.require()`; +* в BH — из пространства имен `bh.lib`. > Подробнее о том, как подключаются сторонние библиотеки смотрите в документации к пакетам [enb-bemxjst](https://github.com/enb-bem/enb-bemxjst/blob/master/README.md#Подключение-сторонних-библиотек) и [enb-bh](https://github.com/enb-bem/enb-bh/blob/master/README.md#Подключение-сторонних-библиотек). -`i18n`-файлы нужно собирать так, чтобы `i18n`-функция была доступна из переменной `BEM.I18N` в любой среде исполнения. Для этого следует использовать опцию [exports](api.ru.md) со значением `{ globals: 'force' }`. +Файлы `i18n` нужно собирать так, чтобы `i18n`-функция была доступна из переменной `BEM.I18N` в любой среде исполнения. Для этого следует использовать опцию [exports](api.ru.md) со значением `{ globals: 'force' }`. **Пример сборки BEMHTML и BH шаблонов** @@ -388,9 +392,9 @@ module.exports = function(config) { ### Сборка только необходимых переводов -Если в браузере используется лишь часть переводов (например, когда остальные переводы применяются при шаблонизации в `Node.js`), то для экономии можно собрать только их. +Если в браузере используется только часть переводов (например, когда остальные переводы применяются при шаблонизации в `Node.js`), то для экономии можно собрать только необходимое. -Для этого в [файлах зависимостей](https://ru.bem.info/technology/deps/about/) потребуется указать дополнительную информацию о том, какие технологии используют переводы. +Для этого в [файлах зависимостей](https://ru.bem.info/technology/deps/about/) укажите дополнительную информацию о технологиях, которые используют переводы. * При использовании в JavaScript-коде блоков в `deps.js`-файл необходимо добавить зависимость для `js`-технологии. @@ -403,9 +407,9 @@ module.exports = function(config) { } ``` - Такая запись означает, что `js` технология блока зависит от технологии `i18n` этого же блока. Иначе говоря, в JavaScript-коде, предназначенном для работы в браузере, используются переводы. + Такая запись означает, что `js`-технология блока зависит от технологии `i18n` этого же блока. Иначе говоря, в JavaScript-коде, предназначенном для работы в браузере, используются переводы. - **Важно:** если в браузер должны попасть все переводы без исключения, то такая запись не обязательна. + **Важно!** Если в браузер должны попасть все переводы без исключения, то такая запись не обязательна. * При использовании в коде шаблонов в `deps.js`-файл необходимо добавить зависимость для `bemhtml`- или `bh`-технологии. @@ -567,11 +571,11 @@ module.exports = function (config) { ### В JavaScript -Cпособы использования `i18n` в JavaScript зависят от наличия модульной системы и ее типа. Файлы могут подключаться как [в Node.js](#Использование-в-node.js), так и [в браузере](#Использование-в-браузере), независимо от используемой библиотеки (`bem-bl` или `bem-core`). +Cпособы использования `i18n` в JavaScript зависят от наличия модульной системы в проекте и ее типа. Файлы могут подключаться как [в Node.js](#Использование-в-node.js), так и [в браузере](#Использование-в-браузере), независимо от используемой библиотеки (`bem-bl` или `bem-core`). #### Использование в Node.js -Скомпилированный файл подключается как модуль в формате CommonJS. +Скомпилированный файл можно подключить как модуль в формате CommonJS. ```js var i18n = require('bundle.lang.en.js'); // Путь до скомпилированного файла @@ -586,7 +590,7 @@ i18n('scope', 'key'); // 'val' * **В браузере без YModules как `BEM.I18N`** ```js - BEM.I18N('scope', 'key'); // Ядро `i18n` предоставляется в глобальную видимость в переменную `BEM.I18N`. + BEM.I18N('greeting', 'hello'); // Ядро `i18n` предоставляется в глобальную видимость в переменную `BEM.I18N`. ``` * **В браузере с YModules как `i18n`-модуль** @@ -597,7 +601,7 @@ i18n('scope', 'key'); // 'val' }); ``` ->**Важно!** В проект с модульной системой ядро библиотеки интернационализации подключаются одинаково, как модуль `i18n`, вне зависимости от используемой библиотеки `bem-core` или `bem-bl`. +>**Важно!** В проект с модульной системой ядро библиотеки интернационализации подключаются, как модуль `i18n`, вне зависимости от используемой библиотеки `bem-core` или `bem-bl`. ### В шаблонах @@ -628,11 +632,14 @@ bh.match('block', function (ctx) { }); }); ``` - ## API `i18n` +Описание взаимодействия с ядром `i18n`, результатом которого являются локализованные строки. + ### Инициализация +В разделе рассмотрены примеры инициализации ядра на абстрактных файлах для библиотек `bem-bl` и `bem-core`. + * **В `bem-bl`** ```js @@ -663,19 +670,21 @@ bh.match('block', function (ctx) { i18n('greeting', 'hello'); // Привет! ``` -### Параметризация значений +### Передаваемые параметры функции `i18n` -Функция принимает следующие параметры: +Функция `i18n` принимает следующие параметры: * **scope** — область видимости ключа. Обычно имя блока. * **key** — ключ, соответствующий значению для указанного языка. -* **params** — входные данные для функции. +* **params** — входные данные для функции (дополнительный параметр). + +Параметризация значений позволяет задавать дополнительный параметр **params**, который будет обработан функцией `i18n` и может повлиять на результат перевода. Например, в этом параметре может передаваться число от 1 до 12, при обработке которого результатом будет месяц, соответствующий указанному числу. Результат выполнения: строка, содержащая перевод. * **В `bem-bl`** - Задавать значения ключей можно не только как строку. Также возможность параметризации значений реализована через XML. В строку передается XML, который обрабатывается с помощью специальной программы. + Задавать значения ключей можно не только как строку. Также возможность параметризации значений реализована через XML. ```js { @@ -691,7 +700,7 @@ bh.match('block', function (ctx) { * **В `bem-core`** - Задавать значения ключей можно не только как строку. Параметризация значений реализуется через функцию. + Задавать значения ключей можно не только как строку. Параметризация значений реализована через функцию. Пример: @@ -714,11 +723,11 @@ bh.match('block', function (ctx) { }); ``` -## Отличия в работе +## Различия в использовании `i18n` в `bem-bl` и `bem-core` -### Переключение между языками во время исполнения +### Переключение между языками в runtime -* В `bem-bl` реализована возможность переключения между языками в реальном времени. +* В `bem-bl` реализована возможность переключения между языками в runtime. * В `bem-core` такой возможности нет. ### Хранение общих keysets-файлов с переводами diff --git a/api.ru.md b/api.ru.md index aa7ebc3..b5bdc05 100644 --- a/api.ru.md +++ b/api.ru.md @@ -3,12 +3,12 @@ Пакет предоставляет следующие технологии: * [keysets](#keysets) — служебная технология для сбора исходных файлов с переводами. -* [i18n](#i18n) — технология, которая формирует общий бандл с переводами для каждого языка для дальнейшего использования. -* [keysets-xml](#keysets-xml) — технология для локализации сервисов, использующих XSLT для шаблонизации. +* [i18n](#i18n) — технология, которая формирует общий бандл с переводами для каждого языка. +* [keysets-xml](#keysets-xml) — технология для локализации проектов, использующих XSLT для шаблонизации. ## keysets -Служебная технология. Собирает данные (`keysets`) для указанного языка в `?.keysets..js`-файл на основе `.js`-файлов. +Служебная технология, результат работы которой используется другими технологиями пакета `enb-bem-i18n`. Собирает данные (`keysets`) для указанного языка в `?.keysets..js`-файл на основе `.js`-файлов. ### Опции @@ -33,9 +33,9 @@ Допустимые значения: -* **'lang'** — значение языка (например, `'en'`, `'ru'`), для которого будут собраны данные (`keysets`) из файлов `.js`. +* **'lang'** — значение языка (двухбуквенный код языка, например, `'en'`, `'ru'`), для которого будут собраны данные (`keysets`) из файлов `.js`. -* **'{lang}'** — специальная директива, которая вызывает технологию необходимое количество раз с поочередной подстановкой в `'lang'` всех языков, указанных в параметрах функции `config.setLanguages()`. +* **'{lang}'** — директива, которая вызывает технологию необходимое количество раз с поочередной подстановкой в `'lang'` всех языков, указанных в параметрах функции `config.setLanguages()`. #### dirsTarget @@ -47,7 +47,7 @@ Тип: `String | String[]`. По умолчанию: `['.i18n']`. -Суффиксы директорий, по которым они отбираются для дальнейшей сборки. +Суффиксы директорий, по которым происходит отбор для дальнейшей сборки. ------------------------------------- @@ -91,20 +91,21 @@ module.exports = function(config) { * [target](#target-1) * [lang](#lang-1) -* [keysetsFile](#keysetsfile) +* [keysetsFile](#keysetsаile) * [exports](#exports) #### target Тип: `String`. По умолчанию: `?.lang..js`. -Имя файла, куда будет записан результат сборки необходимых данных из `?.keysets..js`-файла — скомпилированный файл `?.lang..js`. +Имя файла, куда будет записан результат сборки данных из `?.keysets..js`-файла — скомпилированный файл `?.lang..js`. + #### lang Тип: `String`. Обязательная опция. -Язык, для которого необходимо собрать финальный файл, содержащий строки переводов. +Язык, для которого необходимо собрать файл, содержащий строки переводов. Допустимые значения: @@ -122,7 +123,9 @@ module.exports = function(config) { Тип: `Object`. По умолчанию — `{ globals: true, commonJS: true, ym: true }`. -Настраивает способ получения функции `i18n`. Возможные опции: +Настраивает способ получения функции `i18n`. + +Возможные опции: * `globals: true` — функция `i18n` будет доступна из глобальной переменной `BEM.I18N`, если в среде исполнения нет модульных систем. Чтобы глобальная переменная была доступна при наличии модульных систем, нужно указать специальное значение `globals: 'force'`. * `commonJS: true` — скомпилированный файл можно подключить как CommonJS модуль. @@ -130,7 +133,6 @@ module.exports = function(config) { ------------------------------------- **Пример** - ```js var I18NTech = require('enb-bem-i18n/techs/i18n'), KeysetsTech = require('enb-bem-i18n/techs/keysets'),