Документирование локалей

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

Документирование файла локали

/**
 * Русская локаль для timeago.js с полными формами множественного числа.
 *
 * @module locales/ru
 *
 * Поддерживаемые интервалы:
 * - только что / через секунду
 * - N секунд назад / через N секунд
 * - N минут назад / через N минут
 * - N часов назад / через N часов
 * - N дней назад / через N дней
 * - N месяцев назад (через formatDistance, не timeago)
 * - N лет назад / через N лет
 *
 * Склонение числительных:
 * - 1, 21, 31 → минута, час, день
 * - 2-4, 22-24 → минуты, часа, дня
 * - 5-20, 25-30 → минут, часов, дней
 *
 * @see https://github.com/hustcc/timeago.js#locale-function
 */

import { register } from 'timeago.js';
import type { LocaleFunc } from 'timeago.js';

Документирование каждого индекса

/**
 * Функция локали для русского языка.
 *
 * @param {number} n - Количество единиц (подставляется вместо %s).
 * @param {number} i - Индекс интервала:
 *   0  = < 45 секунд ("только что")
 *   1  = 1 секунда
 *   2  = 2-44 секунды
 *   3  = 45-89 секунд ("минуту назад")
 *   4  = 90-2700 секунд (1-2 минуты)
 *   5  = 2-44 минуты
 *   6  = 45-89 минут
 *   7  = 1-2 часа
 *   8  = 2-21 часа
 *   9  = 22-35 часов
 *   10 = 36-86400 секунд (1-2 дня)
 *   11 = 2-25 дней
 *   12 = 26-345 дней
 *   13 = 1-2 года
 *   14 = > 2 лет
 * @returns {[string, string]} Кортеж [прошлое, будущее].
 */
export const ruLocale: LocaleFunc = (n, i) => {
  // ...
};

Таблица форм в документации

/**
 * Таблица форм русской локали:
 *
 * | i  | n  | Прошлое              | Будущее              |
 * |----|-----|----------------------|----------------------|
 * | 0  | -   | только что           | сейчас               |
 * | 1  | 1   | 1 секунду назад      | через 1 секунду      |
 * | 2  | 2   | 2 секунды назад      | через 2 секунды      |
 * | 2  | 5   | 5 секунд назад       | через 5 секунд       |
 * | 3  | -   | минуту назад         | через минуту         |
 * | 4  | -   | минуту назад         | через минуту         |
 * | 5  | 5   | 5 минут назад        | через 5 минут        |
 * | 6  | -   | час назад            | через час            |
 * | 7  | -   | час назад            | через час            |
 * | 8  | 3   | 3 часа назад         | через 3 часа         |
 * | 9  | -   | день назад           | через день           |
 * | 10 | -   | день назад           | через день           |
 * | 11 | 5   | 5 дней назад         | через 5 дней         |
 * | 12 | 3   | 3 месяца назад       | через 3 месяца       |
 * | 13 | -   | год назад            | через год            |
 * | 14 | 5   | 5 лет назад          | через 5 лет          |
 */

LOCALE_MAP — документирование реестра

/**
 * Карта поддерживаемых локалей.
 * Ключ: код локали для timeago.js.
 * Значение: человекочитаемое название.
 *
 * Обновлять при добавлении новых локалей.
 * Локали должны быть зарегистрированы через register() до использования.
 *
 * @see timeago.js/esm/lang/ — исходные файлы встроенных локалей
 */
export const SUPPORTED_LOCALES: Record<string, string> = {
  ru:    'Русский',
  en_US: 'English (US)',
  de:    'Deutsch',
  fr:    'Français',
  es:    'Español',
  zh_CN: '中文（简体）',
  zh_TW: '中文（繁體）',
  ja:    '日本語',
  ko:    '한국어',
  ar:    'العربية',
} as const;

Документирование RTL локалей

/**
 * Коды локалей с направлением текста справа налево (RTL).
 * Для корректного отображения элементы с этими локалями
 * должны иметь атрибут dir="rtl" или CSS direction: rtl.
 *
 * @see https://www.w3.org/International/questions/qa-html-dir
 */
export const RTL_LOCALES: ReadonlySet<string> = new Set(['ar', 'he', 'fa', 'ur']);

Документирование кастомной локали с особенностями

/**
 * Украинская локаль для timeago.js.
 *
 * Особенности:
 * - Три формы множественного числа (как в русском):
 *   1, 21, 31 → хвилина, секунда
 *   2-4, 22-24 → хвилини, секунди
 *   5-20, 25-30 → хвилин, секунд
 *
 * - Специфические формы для 1-го и 2-го лица:
 *   "щойно" вместо "тільки що" для i=0
 *
 * - Проверено на соответствие с встроенной uk-локалью timeago.js v4.0.
 */
export const ukLocale: LocaleFunc = (n, i) => { /* ... */ };

Документирование процесса регистрации

/**
 * Инициализирует все локали приложения.
 * Вызывается один раз при старте приложения.
 *
 * Порядок важен: ru должна быть зарегистрирована до использования format('ru').
 * При lazy-loading локалей использовать loadLocale() вместо этой функции.
 *
 * @returns {void}
 */
export function initLocales(): void {
  register('ru', ruLocale);
  register('en_US', enLocale);
  register('de', deLocale);
}
Оглавление