Перевод вашего сайта на Vite и Svelte с использованием Intlayer | Интернационализация (i18n)

Содержание

Что такое Intlayer?

Intlayer — это инновационная, открытая библиотека интернационализации (i18n), созданная для упрощения поддержки многоязычности в современных веб-приложениях.

С Intlayer вы можете:

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

Пошаговое руководство по настройке Intlayer в приложении на Vite и Svelte

Смотрите Шаблон приложения на GitHub.

Шаг 1: Установка зависимостей

Установите необходимые пакеты с помощью npm:

npm install intlayer svelte-intlayernpm install vite-intlayer --save-dev

• intlayer

  Основной пакет, предоставляющий инструменты интернационализации для управления конфигурацией, перевода, объявления контента, транспиляции и CLI-команд.

• svelte-intlayer Пакет, который интегрирует Intlayer с приложением на Svelte. Он предоставляет провайдеры контекста и хуки для интернационализации в Svelte.

• vite-intlayer Включает плагин Vite для интеграции Intlayer с сборщиком Vite, а также middleware для определения предпочтительной локали пользователя, управления cookie и обработки перенаправления URL.

Шаг 2: Конфигурация вашего проекта

Создайте файл конфигурации для настройки языков вашего приложения:

import { Locales, type IntlayerConfig } from "intlayer";const config: IntlayerConfig = {  internationalization: {    locales: [      Locales.ENGLISH,      Locales.FRENCH,      Locales.SPANISH,      // Ваши другие локали    ],    defaultLocale: Locales.ENGLISH,  },};export default config;

Через этот файл конфигурации вы можете настроить локализованные URL, перенаправление в middleware, имена cookie, расположение и расширение ваших деклараций контента, отключить логи Intlayer в консоли и многое другое. Для полного списка доступных параметров обратитесь к документации по конфигурации.

Шаг 3: Интеграция Intlayer в вашу конфигурацию Vite

Добавьте плагин intlayer в вашу конфигурацию.

import { defineConfig } from "vite";import { svelte } from "@sveltejs/vite-plugin-svelte";import { intlayer } from "vite-intlayer";// https://vitejs.dev/config/export default defineConfig({  plugins: [svelte(), intlayer()],});

Плагин Vite intlayer() используется для интеграции Intlayer с Vite. Он обеспечивает сборку файлов деклараций контента и отслеживает их в режиме разработки. Определяет переменные окружения Intlayer внутри приложения Vite. Кроме того, предоставляет алиасы для оптимизации производительности.

Шаг 4: Объявите ваш контент

Создайте и управляйте декларациями контента для хранения переводов:

import { t, type Dictionary } from "intlayer";const appContent = {  key: "app",  content: {    title: t({      en: "Hello World",      fr: "Bonjour le monde",      es: "Hola mundo",    }),  },} satisfies Dictionary;export default appContent;

Ваши объявления контента могут быть определены в любом месте вашего приложения, как только они будут включены в директорию contentDir (по умолчанию, ./src). И соответствовать расширению файла объявления контента (по умолчанию, .content.{json,ts,tsx,js,jsx,mjs,mjx,cjs,cjx}).

Для получения дополнительной информации обратитесь к документации по объявлению контента.

Шаг 5: Использование Intlayer в вашем коде

<script>  import { useIntlayer } from "svelte-intlayer";  const content = useIntlayer("app");</script><div><!-- Отобразить контент как простой контент --><h1>{$content.title}</h1><!-- Отобразить контент с возможностью редактирования через редактор --><h1><svelte:component this={$content.title} /></h1><!-- Отобразить контент как строку --><div aria-label={$content.title.value}></div>

(Необязательно) Шаг 6: Изменение языка вашего контента

<script lang="ts">import  { getLocaleName } from 'intlayer';import { useLocale } from 'svelte-intlayer';// Получить информацию о локали и функцию setLocaleconst { locale, availableLocales, setLocale } = useLocale();// Обработка изменения локалиconst changeLocale = (event: Event) => {  const target = event.target as HTMLSelectElement;  const newLocale = target.value;  setLocale(newLocale);};</script><div>  <select value={$locale} on:change={changeLocale}>    {#each availableLocales ?? [] as loc}      <option value={loc}>        {getLocaleName(loc)}      </option>    {/each}  </select></div>

(Необязательно) Шаг 7: Отображение Markdown

Intlayer поддерживает отображение контента в формате Markdown непосредственно в вашем приложении на Svelte. По умолчанию Markdown обрабатывается как простой текст. Чтобы преобразовать Markdown в насыщенный HTML, вы можете интегрировать @humanspeak/svelte-markdown или другой парсер Markdown.

Чтобы узнать, как объявлять контент в формате markdown с использованием пакета intlayer, смотрите документацию по markdown.

<script>  import { setIntlayerMarkdown } from "svelte-intlayer";  setIntlayerMarkdown((markdown) =>   // рендеринг содержимого markdown как строки   return markdown;  );</script><h1>{$content.markdownContent}</h1>

Вы также можете получить доступ к данным front-matter вашего markdown через свойство content.markdownContent.metadata.xxx.

(Необязательно) Шаг 8: Настройка редактора / CMS intlayer

Для настройки редактора intlayer необходимо следовать документации редактора intlayer.

Для настройки CMS intlayer необходимо следовать документации CMS intlayer.

Параллельно, в вашем приложении на Svelte, вы должны добавить следующую строку в layout или в корень вашего приложения:

import { useIntlayerEditor } from "svelte-intlayer";useIntlayerEditor();

(Необязательно) Шаг 7: Добавьте локализованную маршрутизацию в ваше приложение

Для обработки локализованной маршрутизации в вашем приложении на Svelte вы можете использовать svelte-spa-router вместе с localeFlatMap из Intlayer для генерации маршрутов для каждой локали.

Сначала установите svelte-spa-router:

npm install svelte-spa-router

Затем создайте файл Router.svelte для определения ваших маршрутов:

<script lang="ts">import { localeFlatMap } from "intlayer";import Router from "svelte-spa-router";import { wrap } from "svelte-spa-router/wrap";import App from "./App.svelte";const routes = Object.fromEntries(    localeFlatMap(({locale, urlPrefix}) => [    [        urlPrefix || '/',        wrap({            component: App as any,            props: {                locale,            },        }),    ],    ]));</script><Router {routes} />

Обновите ваш main.ts, чтобы монтировать компонент Router вместо App:

import { mount } from "svelte";import Router from "./Router.svelte";const app = mount(Router, {  target: document.getElementById("app")!,});export default app;

Наконец, обновите ваш App.svelte, чтобы принимать проп locale и использовать его с useIntlayer:

<script lang="ts">import type { Locale } from 'intlayer';import { useIntlayer } from 'svelte-intlayer';import Counter from './lib/Counter.svelte';import LocaleSwitcher from './lib/LocaleSwitcher.svelte';export let locale: Locale;// Используем хук useIntlayer для получения контента на основе текущей локали$: content = useIntlayer('app', locale);</script><main>  <div class="locale-switcher-container">    <LocaleSwitcher currentLocale={locale} />  </div>  <!-- ... остальная часть вашего приложения ... --></main>

Настройка маршрутизации на стороне сервера (необязательно)

Параллельно вы также можете использовать intlayerProxy для добавления маршрутизации на стороне сервера в ваше приложение. Этот плагин автоматически определит текущую локаль на основе URL и установит соответствующее cookie с локалью. Если локаль не указана, плагин определит наиболее подходящую локаль на основе языковых предпочтений браузера пользователя. Если локаль не будет обнаружена, произойдет перенаправление на локаль по умолчанию.

Обратите внимание, что для использования intlayerProxy в продакшене необходимо перевести пакет vite-intlayer из devDependencies в dependencies.

import { defineConfig } from "vite";import { svelte } from "@sveltejs/vite-plugin-svelte";import { intlayer, intlayerProxy } from "vite-intlayer";  plugins: [svelte(), intlayer(), intlayerProxy()],});

(Необязательно) Шаг 8: Изменение URL при смене локали

Чтобы позволить пользователям переключать языки и обновлять URL соответствующим образом, вы можете создать компонент LocaleSwitcher. Этот компонент будет использовать getLocalizedUrl из intlayer и push из svelte-spa-router.

<script lang="ts">import { getLocaleName, getLocalizedUrl } from "intlayer";import { useLocale } from "svelte-intlayer";import { push } from "svelte-spa-router";export let currentLocale: string | undefined = undefined;// Получение информации о локалиconst { locale, availableLocales } = useLocale();// Обработка изменения локалиconst changeLocale = (event: Event) => {  const target = event.target as HTMLSelectElement;  const newLocale = target.value;  const currentUrl = window.location.pathname;  const url = getLocalizedUrl( currentUrl, newLocale);  push(url);};</script><div class="locale-switcher">  <select value={currentLocale ?? $locale} onchange={changeLocale}>    {#each availableLocales ?? [] as loc}      <option value={loc}>        {getLocaleName(loc)}      </option>    {/each}  </select></div>

Конфигурация Git

Рекомендуется игнорировать файлы, сгенерированные Intlayer. Это позволит избежать их коммита в ваш репозиторий Git.

Для этого вы можете добавить следующие инструкции в ваш файл .gitignore:

# Игнорировать файлы, сгенерированные Intlayer.intlayer

Расширение VS Code

Чтобы улучшить ваш опыт разработки с Intlayer, вы можете установить официальное расширение Intlayer для VS Code.

Установить из VS Code Marketplace

Это расширение предоставляет:

• Автозаполнение ключей переводов.
• Обнаружение ошибок в реальном времени для отсутствующих переводов.
• Встроенный просмотр переведенного контента.
• Быстрые действия для удобного создания и обновления переводов.

Для получения дополнительной информации о том, как использовать расширение, обратитесь к документации расширения Intlayer для VS Code.

Продвинуться дальше

Чтобы продвинуться дальше, вы можете реализовать визуальный редактор или вынести ваш контент, используя CMS.