Структура переводов

Stencil — это инструмент для создания современных веб-компонентов, который позволяет разработчикам строить веб-приложения с использованием компонентов, поддерживающих Web Components, Custom Elements и другие стандарты. Важной частью работы с такими компонентами является возможность интернационализации (i18n), которая обеспечивает поддержку различных языков и локализаций.

В Stencil структура переводов является важным аспектом разработки, особенно при создании многоязычных приложений. Для этого Stencil предоставляет механизм, который позволяет управлять переводами с помощью простых и гибких инструментов.

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

Stencil использует концепцию перевода текстовых строк, которая встраивается в компоненты через JSON-файлы. Эти файлы содержат ключи и значения, которые соответствуют текстам на разных языках. Структура переводов в Stencil имеет несколько ключевых элементов:

  1. Ключи — это уникальные идентификаторы для каждой строки, которая должна быть переведена. Они используются в компонентах для замены исходных текстов на переведенные строки.

  2. Значения — это сами переводы, которые соответствуют ключам и определяются для каждого языка отдельно.

  3. Языковые файлы — это JSON-файлы, которые содержат пары ключ-значение для каждого поддерживаемого языка. Например, для английского и русского языков будут созданы два отдельных файла.

Пример структуры перевода для английского и русского языков:

// en.json
{
  "greeting": "Hello",
  "farewell": "Goodbye"
}

// ru.json
{
  "greeting": "Привет",
  "farewell": "До свидания"
}

Работа с переводами в Stencil

Для использования переводов в компонентах Stencil необходимо установить и настроить несколько инструментов. Один из популярных подходов — это использование сторонних библиотек, таких как @stencil/i18n. Однако можно обойтись и без них, вручную интегрируя систему переводов.

Шаг 1: Подключение переводов

Для начала нужно загрузить переводы в приложение. Это можно сделать с помощью динамической загрузки JSON-файлов или же импортировать их непосредственно в компонент. Пример простого импорта:

import en from './locales/en.json';
import ru from './locales/ru.json';

const translations = {
  en,
  ru,
};
Шаг 2: Переключение языка

Для смены языка в приложении можно использовать глобальное состояние или контекст. Например, создание простого сервиса для управления текущим языком и доступом к переводам:

let currentLang = 'en';

function setLanguage(lang: string) {
  currentLang = lang;
}

function translate(key: string) {
  return translations[currentLang][key] || key;
}

Теперь, чтобы отобразить перевод в компоненте, достаточно вызвать функцию translate с нужным ключом:

@Component({
  tag: 'my-component',
  styleUrl: 'my-component.css',
  shadow: true,
})
export class MyComponent {

  @State() currentLang: string = 'en';

  render() {
    return (
      <div>
        <h1>{translate('greeting')}</h1>
        <button>{translate('farewell')}</button>
      </div>
    );
  }
}
Шаг 3: Обработка динамических переводов

Stencil позволяет использовать переменные и динамические значения в строках переводов. Например, можно использовать плейсхолдеры в тексте и заменять их на значения во время рендеринга. Для этого потребуется форматирование строки перед рендерингом.

Пример перевода с плейсхолдерами:

// en.json
{
  "greeting": "Hello, {name}!"
}

// ru.json
{
  "greeting": "Привет, {name}!"
}

Для использования таких переводов можно написать функцию форматирования:

function formatTranslation(key: string, params: { [key: string]: string }) {
  let translation = translations[currentLang][key] || key;
  for (const param in params) {
    translation = translation.replace(`{${param}}`, params[param]);
  }
  return translation;
}

render() {
  return (
    <div>
      <h1>{formatTranslation('greeting', { name: 'Алексей' })}</h1>
    </div>
  );
}
Шаг 4: Поддержка разных форматов и дополнительных функций

Stencil не ограничивает разработчика одним форматом перевода. Можно интегрировать более сложные решения для работы с датами, числами, валютами и т.д. В таких случаях можно использовать внешние библиотеки, например, formatjs или i18next, которые предоставляют расширенные возможности для локализации и форматирования данных.

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

import { DateTime } from 'luxon';

function translateDate(key: string, date: Date) {
  const formattedDate = DateTime.fromJSDate(date).toLocaleString(DateTime.DATE_FULL);
  return formatTranslation(key, { date: formattedDate });
}

render() {
  const currentDate = new Date();
  return (
    <div>
      <p>{translateDate('eventDate', currentDate)}</p>
    </div>
  );
}

Поддержка динамических переводов и их обновление

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

Для реализации такого поведения можно использовать дополнительные механизмы, такие как @Watch в Stencil или глобальные события. Например, можно слушать события изменения языка и автоматически обновлять переводы:

@Watch('currentLang')
languageChanged(newLang: string) {
  this.updateTranslations(newLang);
}

updateTranslations(lang: string) {
  // Логика обновления переводов
}

Разделение переводов по модулям

В больших приложениях может возникнуть необходимость разделять переводы по модулям или компонентам, чтобы избежать дублирования и упростить поддержку. Это можно сделать, разбив JSON-файлы на более мелкие части, например:

// en.json
{
  "common": {
    "greeting": "Hello",
    "farewell": "Goodbye"
  },
  "errors": {
    "network": "Network error occurred",
    "404": "Page not found"
  }
}

Такой подход облегчает управление переводами и упрощает их структуру, что особенно важно при работе с крупными проектами.

Заключение

Правильная организация структуры переводов и управление языковыми файлами являются основой для успешной интернационализации приложения на Stencil. Разработчики могут гибко использовать различные подходы для загрузки, обновления и обработки переводов, обеспечивая поддержку множества языков и локализаций.

Оглавление