Соглашения об именовании

В экосистеме Globalize ключевым элементом именования выступают локали, поскольку вся модель работы библиотеки строится вокруг CLDR-данных и их строгой идентификации. Локаль задаётся строкой стандарта IETF BCP 47 и обычно имеет иерархическую структуру:

  • базовый язык: en, ru, de
  • язык + регион: en-US, ru-RU, pt-BR
  • язык + script + регион (реже): zh-Hans-CN, zh-Hant-TW

Ключевые правила именования локалей

Единый формат регистра Используется стандарт:

  • язык — в нижнем регистре (en, ru)
  • регион — в верхнем регистре (US, RU)
  • script — с заглавной первой буквой (Hans, Hant)

Это важно, поскольку Globalize напрямую сопоставляет идентификаторы с CLDR-наборами, где отклонение от регистра приводит к отсутствию данных.

Недопустимость произвольных модификаций Не используются кастомные разделители или расширения вида:

  • en_us (ошибочно)
  • EN-us (ошибочно)
  • enUS (ошибочно)

Любые отклонения нарушают загрузку CLDR и приводят к частичному или полному отсутствию локализации.

Именование при загрузке CLDR-данных

Globalize не содержит встроенных локалей и требует явной загрузки данных CLDR. При этом важно соблюдать строгую структуру путей и файлов.

Базовые соглашения

CLDR-пакеты импортируются по схеме:

  • cldr-data/supplemental/likelySubtags
  • cldr-data/main/{locale}/numbers
  • cldr-data/main/{locale}/ca-gregorian

Здесь {locale} всегда соответствует строго нормализованному идентификатору.

Принцип группировки

Имена файлов и путей соответствуют типу данных:

  • numbers — числовые форматы
  • currencies — валюты
  • ca-gregorian — календарь
  • timeZoneNames — часовые пояса

Единообразие структуры критично: любые отклонения в именах модулей приводят к невозможности корректной инициализации Globalize.

Именование экземпляров Globalize

Экземпляры Globalize создаются через привязку к локали:

const Globalize = require("globalize");

const cldr = require("cldr-data");
Globalize.load(cldr);

const gEn = new Globalize("en");
const gRu = new Globalize("ru");

Соглашения для переменных экземпляров

Используется короткий префикс + локаль:

  • gEn
  • gRu
  • gEnUS
  • gPtBR

Недопустимые формы

  • globalizeEN
  • GlobalizeEnglish
  • g_en_us (не соответствует стилю JS в экосистеме библиотеки)

Именование методов API

Globalize предоставляет функциональные методы, которые следуют строгой глагольной структуре.

Основные группы методов

Форматирование

  • formatDate
  • formatNumber
  • formatCurrency
  • formatMessage

Парсинг

  • parseDate
  • parseNumber
  • parseCurrency

Утилитарные операции

  • cldr (доступ к данным)
  • load (загрузка CLDR)
  • locale (работа с локалью)

Принципы именования методов

Глагол + объект Методы строятся по схеме:

action + target

Примеры:

  • format + Date
  • parse + Number

Единообразие регистра (camelCase) Все методы строго используют lowerCamelCase:

  • корректно: formatCurrency
  • некорректно: FormatCurrency, format_currency

Именование сообщений (MessageFormat)

Globalize использует ICU MessageFormat для локализованных строк. Здесь действуют отдельные правила именования ключей.

Структура ключей сообщений

Ключи сообщений — это идентификаторы, которые используются для обращения к текстам:

Globalize("en").formatMessage("greeting", { name: "John" });

Правила именования ключей

1. camelCase как стандарт

  • greetingMessage
  • userName
  • cartItemCount

2. отсутствие пробелов и спецсимволов

Недопустимо:

  • greeting message
  • greeting-message
  • greeting.message

3. семантическая ясность

Ключи должны отражать смысл:

  • errorNetworkTimeout
  • buttonSubmitLabel
  • invoiceTotalAmount

Параметры сообщений и именование плейсхолдеров

Внутри ICU-шаблонов используются именованные параметры.

Соглашения для параметров

  • camelCase: userName, itemCount
  • без сокращений, если они неоднозначны
  • предпочтение полным словам

Пример:

Hello {userName}, you have {itemCount} messages.

Нежелательные формы

  • {u}, {n} — теряют смысл
  • {user_name} — несоответствие camelCase
  • {UserName} — нарушение единообразия с JS-переменными

Именование числовых форм и plural rules

Globalize опирается на CLDR plural rules. Хотя сами категории фиксированы, их использование в коде требует строгого соответствия.

Категории множественного числа

Используются стандартные CLDR-ключи:

  • one
  • few
  • many
  • other

Правила именования в структурах данных

При хранении сообщений применяются вложенные структуры:

const messages = {
  itemCount: {
    one: "{count} item",
    other: "{count} items"
  }
};

Соглашения

  • ключи категорий не изменяются
  • не допускается локализация ключей (odin, mnogo)
  • не допускается произвольное расширение (veryMany)

Именование форматов валют и чисел

Globalize использует CLDR-стандарты для валют и чисел.

Валютные коды

Используются ISO 4217:

  • USD
  • EUR
  • JPY
  • KZT

Недопустимо:

  • usd
  • dollar
  • us-dollars

Числовые форматы

Форматы задаются именами, а не произвольными строками:

  • decimal
  • percent
  • scientific

Пример:

g.formatNumber(1234.56, { style: "decimal" });

Именование переменных в приложении при использовании Globalize

Интеграция Globalize в кодовую базу требует унификации переменных.

Рекомендуемая схема

  • globalize — базовый импорт
  • g — сокращённый алиас (в небольших модулях)
  • i18n — слой абстракции над Globalize

Примеры

const i18n = new Globalize("ru");

const formatted = i18n.formatDate(new Date());

Нежелательные схемы

  • globalization
  • global
  • intlGlobalize (избыточное дублирование смысла)

Именование слоёв абстракции i18n

В архитектурах, где Globalize используется как нижний уровень, вводятся дополнительные соглашения.

Типовые сущности

  • i18nService
  • localeService
  • formatProvider

Принципы

  • суффикс Service используется для сервисов
  • Provider — для поставщиков форматов
  • Manager — избегается как слишком абстрактный и перегруженный термин

Именование конфигураций локализации

Конфигурационные объекты следуют строгой структуре.

Базовая схема

const i18nConfig = {
  defaultLocale: "en",
  supportedLocales: ["en", "ru"]
};

Правила именования полей

  • camelCase
  • без сокращений loc (вместо locale)
  • явные имена defaultLocale, а не defLoc

Недопустимые формы

  • default_language
  • defLocale
  • locale_list

Именование файлов в проекте

При использовании Globalize в проектной структуре важна единая система именования файлов локализации.

Стандартная структура

  • locales/en.js
  • locales/ru.js
  • i18n/messages.en.js
  • i18n/messages.ru.js

Принципы

  • ISO-код языка в имени файла
  • отсутствие пробелов
  • использование точечного разделителя только для модулей (messages.en.js)

Ошибочные подходы

  • englishMessages.js
  • ru-RU.js
  • Messages_RU.js

Соглашения для ключей временных форматов

Globalize опирается на CLDR при форматировании дат и времени.

Именование шаблонов

  • short
  • medium
  • long
  • full

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

g.formatDate(date, { datetime: "short" });

Принцип неизменности

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

Именование расширений и пользовательских утилит

При создании обёрток над Globalize часто вводятся дополнительные функции.

Рекомендуемые соглашения

  • префикс format
  • префикс parse
  • суффикс Util или Helper (ограниченно)

Примеры:

  • formatPrice
  • formatDateLocalized
  • parseUserDate

Антипаттерны

  • doFormat
  • makeDate
  • convertNumberToString (избыточная длина без стандартизации)

Соглашения для нейминга в тестах Globalize-интеграций

Тестовые файлы и сущности должны отражать локализацию.

Принципы

  • globalize.formatDate.spec.js
  • i18n.messages.test.js

Именование тестов

  • formats date in en-US locale
  • parses number correctly for ru-RU

Недопустимо

  • test1.js
  • globalizeTest.js
  • localeTestFinal.js
Оглавление