Перекладіть свій сайт на SvelteKit із Intlayer | Інтернаціоналізація (i18n)

Зміст

Чому варто обрати Intlayer, а не альтернативи?

Порівняно з основними рішеннями, такими як svelte-i18n або i18next, Intlayer — це рішення, яке має такі інтегровані оптимізації, як:

Покроковий посібник із налаштування Intlayer у застосунку SvelteKit

Див. Шаблон застосунку на GitHub.

Щоб почати, створіть новий проєкт SvelteKit. Ось кінцева структура, яку ми створимо:

.├── intlayer.config.ts├── package.json├── src│   ├── app.d.ts│   ├── app.html│   ├── hooks.server.ts│   ├── lib│   │   ├── getLocale.ts│   │   ├── LocaleSwitcher.svelte│   │   └── LocalizedLink.svelte│   ├── params│   │   └── locale.ts│   └── routes│       ├── [[locale=locale]]│       │   ├── +layout.svelte│       │   ├── +layout.ts│       │   ├── +page.svelte│       │   ├── +page.ts│       │   ├── about│       │   │   ├── +page.svelte│       │   │   ├── +page.ts│       │   │   └── page.content.ts│       │   ├── Counter.content.ts│       │   ├── Counter.svelte│       │   ├── Header.content.ts│       │   ├── Header.svelte│       │   ├── home.content.ts│       │   └── layout.content.ts│       ├── +layout.svelte│       └── layout.css├── static│   ├── favicon.svg│   └── robots.txt├── svelte.config.js├── tsconfig.json└── vite.config.ts

1. 1

   Встановлення залежностей

   Встановіть необхідні пакети за допомогою npm:

   bash

   Копіювати вміст

   Копіювати код

   Скопіюйте код у буфер обміну

   npm install intlayer svelte-intlayernpm install vite-intlayer --save-devnpx intlayer init

   • intlayer: Основний пакет i18n.
   • svelte-intlayer: Надає провайдери контексту та stores для Svelte/SvelteKit.
   • vite-intlayer: Плагін Vite для інтеграції декларацій контенту в процес збірки.
2. 2

   Налаштування вашого проєкту

   Створіть файл конфігурації в корені вашого проєкту:

   intlayer.config.ts

   Копіювати вміст

   Копіювати код

   Скопіюйте код у буфер обміну

   import { Locales, type IntlayerConfig } from "intlayer";const config: IntlayerConfig = {  internationalization: {    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],    defaultLocale: Locales.ENGLISH,  },};export default config;

3. 3

   Інтеграція Intlayer у вашу Vite конфігурацію

   Оновіть ваш vite.config.ts, щоб додати плагін Intlayer. Цей плагін обробляє транспіляцію ваших файлів вмісту.

   vite.config.ts

   Копіювати вміст

   Копіювати код

   Скопіюйте код у буфер обміну

   import { sveltekit } from "@sveltejs/kit/vite";import { defineConfig } from "vite";import { intlayer } from "vite-intlayer";export default defineConfig({  plugins: [intlayer(), sveltekit()], // порядок важливий: Intlayer має стояти перед SvelteKit});

4. 4

   Оголосіть ваш вміст

   Створюйте файли декларацій контенту в будь-якому місці вашої папки src (наприклад, src/lib/content або поруч із компонентами). Ці файли визначають перекладний контент для вашого застосунку, використовуючи функцію t() для кожної локалі.

5. 5

   Використання Intlayer у ваших компонентах

   Тепер ви можете використовувати функцію useIntlayer у будь-якому Svelte-компоненті. Вона повертає реактивний store, який автоматично оновлюється при зміні локалі. Функція автоматично враховує поточну локаль (як під час SSR, так і під час навігації на боці клієнта).

   Примітка: useIntlayer повертає Svelte-store, тому потрібно використовувати префікс $ для доступу до його реактивного значення (наприклад, $content.title).

   src/lib/components/Component.svelte

   Копіювати вміст

   Копіювати код

   Скопіюйте код у буфер обміну

   <script lang="ts">  import { useIntlayer } from "svelte-intlayer";  // "hero-section" відповідає ключу, визначеному в кроці 4  const content = useIntlayer("hero-section");</script><!-- Відобразити контент у простому вигляді --><h1>{$content.title}</h1><!-- Щоб зробити контент редагованим за допомогою редактора --><h1>{@const Title = $content.title}<Title /></h1><!-- Щоб відобразити вміст як рядок --><div aria-label={$content.title.value}></div><div aria-label={$content.title.toString()}></div><div aria-label={String($content.title)}></div>

6. 6

   Налаштування маршрутизації

   Необов'язково

   Нижче наведено кроки для налаштування маршрутизації на основі локалі в SvelteKit. Це дозволяє додавати префікс локалі до ваших URL (наприклад, /en/about, /fr/about) для кращого SEO та зручності користувача.

   bash

   Копіювати вміст

   Копіювати код

   Скопіюйте код у буфер обміну

   .└─── src    ├── app.d.ts                  # Визначте тип локалі    ├── hooks.server.ts           # Керує маршрутизацією локалей    ├── lib    │   └── getLocale.ts          # Перевіряє локаль у заголовках та cookie    ├── params    │   └── locale.ts             # Визначає параметр локалі    └── routes        ├── [[locale=locale]]     # Обгорнути в групу маршрутів для встановлення локалі        │   ├── +layout.svelte    # Локальний layout для маршруту        │   ├── +layout.ts        │   ├── +page.svelte        │   ├── +page.ts        │   └── about        │       ├── +page.svelte        │       └── +page.ts        └── +layout.svelte         # Root layout для шрифтів і глобальних стилів

7. 7

   Обробка визначення локалі на сервері

   У SvelteKit сервер повинен знати локаль користувача, щоб відрендерити правильний вміст під час SSR. Ми використовуємо hooks.server.ts для виявлення локалі з URL або cookies.

   Створіть або змініть src/hooks.server.ts:

   src/hooks.server.ts

   Копіювати вміст

   Копіювати код

   Скопіюйте код у буфер обміну

   import type { Handle } from "@sveltejs/kit";import { getLocalizedUrl } from "intlayer";import { getLocale } from "$lib/getLocale";export const handle: Handle = async ({ event, resolve }) => {  const detectedLocale = getLocale(event);  // Перевіряємо, чи поточний шлях вже починається з локалі (наприклад, /fr, /en)  const pathname = event.url.pathname;  const targetPathname = getLocalizedUrl(pathname, detectedLocale);  // Якщо в URL немає локалі (наприклад, користувач відвідує "/"), перенаправляємо його  if (targetPathname !== pathname) {    return new Response(undefined, {      headers: { Location: targetPathname },      status: 307, // Тимчасове перенаправлення    });  }  return resolve(event, {    transformPageChunk: ({ html }) => html.replace("%lang%", detectedLocale),  });};

   Потім створіть допоміжну функцію для отримання локалі користувача з події запиту:

   src/lib/getLocale.ts

   Копіювати вміст

   Копіювати код

   Скопіюйте код у буфер обміну

   import {  configuration,  getLocaleFromStorage,  localeDetector,  type Locale,} from "intlayer";import type { RequestEvent } from "@sveltejs/kit";/** * Отримати локаль користувача з події запиту. * Ця функція використовується в хуку `handle` у `src/hooks.server.ts`. * * Спочатку вона намагається отримати локаль із сховища Intlayer (кукі або користувацькі заголовки). * Якщо локаль не знайдено, відбувається відкат до переговору браузера через заголовок `Accept-Language`. * * @param event - подія запиту від SvelteKit * @returns локаль користувача */export const getLocale = (event: RequestEvent): Locale => {  const defaultLocale = configuration?.internationalization?.defaultLocale;  // Спроба отримати локаль зі сховища Intlayer (кукі або заголовки)  const storedLocale = getLocaleFromStorage({    // Доступ до cookie SvelteKit    getCookie: (name: string) => event.cookies.get(name) ?? null,    // Доступ до заголовків SvelteKit    getHeader: (name: string) => event.request.headers.get(name) ?? null,  });  if (storedLocale) {    return storedLocale;  }  // Відкат до погодження браузера по заголовку "Accept-Language"  const negotiatorHeaders: Record<string, string> = {};  // Перетворити об'єкт Headers SvelteKit у простий Record<string, string>  event.request.headers.forEach((value, key) => {    negotiatorHeaders[key] = value;  });  // Перевірити локаль із заголовка `Accept-Language`  const userFallbackLocale = localeDetector(negotiatorHeaders);  if (userFallbackLocale) {    return userFallbackLocale;  }  // Повернути локаль за замовчуванням, якщо відповідність не знайдено  return defaultLocale;};

   getLocaleFromStorage перевірятиме локаль у заголовку або cookie залежно від вашої конфігурації. Див. розділ Configuration для детальнішої інформації.

   Функція localeDetector обробляє заголовок Accept-Language і повертає найкраще співпадіння.

   Якщо локаль не налаштована, ми хочемо повернути помилку 404. Щоб спростити це, ми можемо створити функцію match, яка перевіряє, чи є локаль валідною:

   /src/params/locale.ts

   Копіювати вміст

   Копіювати код

   Скопіюйте код у буфер обміну

   export const match = (param: Locale = defaultLocale): boolean =>  locales.includes(param);

   Примітка: Переконайтеся, що у вашому src/app.d.ts міститься визначення локалі:

   typescript

   Копіювати вміст

   Копіювати код

   Скопіюйте код у буфер обміну

   declare global {  namespace App {    interface Locals {      locale: import("intlayer").Locale;    }  }}

   Для файлу +layout.svelte ми можемо видалити все, залишивши лише статичний вміст, не пов'язаний із i18n:

   src/+layout.svelte

   Копіювати вміст

   Копіювати код

   Скопіюйте код у буфер обміну

   <script lang="ts">     import './layout.css';    let { children } = $props();</script><div class="app">    {@render children()}</div><style>    .app {    /*  */    }</style>

   Потім створіть нову сторінку та layout у групі [[locale=locale]]:

   src/routes/[[locale=locale]]/+layout.ts

   Копіювати вміст

   Копіювати код

   Скопіюйте код у буфер обміну

   import type { Load } from "@sveltejs/kit";import { defaultLocale, type Locale } from "intlayer";export const prerender = true;// Використовуйте загальний тип Loadexport const load: Load = ({ params }) => {  const locale: Locale = (params.locale as Locale) ?? defaultLocale;  return {    locale,  };};

   src/routes/[[locale=locale]]/+layout.svelte

   Копіювати вміст

   Копіювати код

   Скопіюйте код у буфер обміну

   <script lang="ts">    import type { Snippet } from 'svelte';    import { useIntlayer, setupIntlayer } from "svelte-intlayer";    import Header from './Header.svelte';    import type { LayoutData } from './$types';    let { children, data }: { children: Snippet, data: LayoutData } = $props();    // Ініціалізує Intlayer з локаллю з маршруту  $effect(() => {      setupIntlayer(data.locale);  });    // Використовує словник вмісту layout    const layoutContent = useIntlayer('layout');</script><Header /><main>    {@render children()}</main><footer>    <p>        {$layoutContent.footer.prefix.value}{' '}        <a href="https://svelte.dev/docs/kit">{$layoutContent.footer.linkLabel.value}</a>{' '}        {$layoutContent.footer.suffix.value}    </p></footer><style>  /*  */</style>

   src/routes/[[locale=locale]]/+page.ts

   Копіювати вміст

   Копіювати код

   Скопіюйте код у буфер обміну

   export const prerender = true;

   src/routes/[[locale=locale]]/+page.svelte

   Копіювати вміст

   Копіювати код

   Скопіюйте код у буфер обміну

   <script lang="ts">    import { useIntlayer } from "svelte-intlayer";    // Використовувати словник контенту для home    const homeContent = useIntlayer('home');</script><svelte:head>    <title>{$homeContent.title.value}</title></svelte:head><section>    <h1>        {$homeContent.title}    </h1></section><style>  /*  */</style>

8. 8

   Інтернаціоналізовані посилання

   Необов'язково

   Для SEO рекомендується додавати префікс локалі до маршрутів (наприклад, /en/about, /fr/about). Цей компонент автоматично додає префікс поточної локалі до будь-якого посилання.

   src/lib/components/LocalizedLink.svelte

   Копіювати вміст

   Копіювати код

   Скопіюйте код у буфер обміну

   <script lang="ts">  import { getLocalizedUrl } from "intlayer";  import { useLocale } from "svelte-intlayer";  let { href = "" } = $props();  const { locale } = useLocale();  // Допоміжна функція для додавання префікса локалі до URL  $: localizedHref = getLocalizedUrl(href, $locale);</script><a href={localizedHref}>  <slot /></a>

   Якщо ви використовуєте goto з SvelteKit, ви можете застосувати ту саму логіку з getLocalizedUrl, щоб перейти на локалізований URL:

   typescript

   Копіювати вміст

   Копіювати код

   Скопіюйте код у буфер обміну

   import { goto } from "$app/navigation";import { getLocalizedUrl } from "intlayer";import { useLocale } from "svelte-intlayer";const { locale } = useLocale();const localizedPath = getLocalizedUrl("/about", $locale);goto(localizedPath); // Переходить на /en/about або /fr/about залежно від локалі

9. 9

   Перемикач мови

   Необов'язково

   Щоб дозволити користувачам переключати мову, оновіть URL.

   src/lib/components/LanguageSwitcher.svelte

   Копіювати вміст

   Копіювати код

   Скопіюйте код у буфер обміну

   <script lang="ts">  import { getLocalizedUrl, getLocaleName } from 'intlayer';  import { useLocale } from "svelte-intlayer";  import { page } from '$app/stores';  import { goto } from '$app/navigation';  const { locale, setLocale, availableLocales } = useLocale({    onLocaleChange: (newLocale) => {      const localizedPath = getLocalizedUrl($page.url.pathname, newLocale);      goto(localizedPath);    },  });</script><ul class="locale-list">  {#each availableLocales as localeEl}    <li>      <a        href={getLocalizedUrl($page.url.pathname, localeEl)}        onclick={(e) => {          e.preventDefault();          setLocale(localeEl); // Встановить локаль у store та викличе onLocaleChange        }}        class:active={$locale === localeEl}      >        {getLocaleName(localeEl)}      </a>    </li>  {/each}</ul><style>  /* */</style>

10. 10

    Додати backend proxy

    Необов'язково

    Щоб додати backend proxy до вашого застосунку SvelteKit, ви можете використати функцію intlayerProxy, що надається плагіном vite-intlayer. Цей плагін автоматично визначатиме найкращу локаль для користувача на основі URL, cookies та мовних налаштувань браузера.

    vite.config.ts

    Копіювати вміст

    Копіювати код

    Скопіюйте код у буфер обміну

    import { defineConfig } from "vite";import { intlayer, intlayerProxy } from "vite-intlayer";import { sveltekit } from "@sveltejs/kit/vite";// https://vitejs.dev/config/export default defineConfig({  plugins: [    intlayerProxy(), // should be placed first    intlayer(),    sveltekit(),  ],],});

11. 11

    Налаштування редактора intlayer / CMS

    Необов'язково

    Щоб налаштувати редактор intlayer, дотримуйтесь документації редактора intlayer.

    Щоб налаштувати CMS intlayer, дотримуйтесь документації CMS intlayer.

    Щоб мати змогу візуалізувати селектор редактора intlayer, потрібно використовувати синтаксис компонента у вашому контенті intlayer.

    Component.svelte

    Копіювати вміст

    Копіювати код

    Скопіюйте код у буфер обміну

    <script lang="ts">  import { useIntlayer } from "svelte-intlayer";  const content = useIntlayer("component");</script><div>  <!-- Відобразити вміст як простий контент -->  <h1>{$content.title}</h1>  <!-- Відобразити вміст як компонент (вимагається редактором) -->  {@const Component = $content.component}<Component /></div>

12. 1

    Витягніть вміст ваших компонентів

    Необов'язково

    Якщо у вас є існуюча кодова база, перетворення тисяч файлів може зайняти багато часу.

    Щоб спростити цей процес, Intlayer пропонує компілятор / екстрактор для перетворення ваших компонентів і витягування вмісту.

    Щоб налаштувати його, ви можете додати розділ compiler у свій файл intlayer.config.ts:

    intlayer.config.ts

    Копіювати вміст

    Копіювати код

    Скопіюйте код у буфер обміну

    import { type IntlayerConfig } from "intlayer";
    
    const config: IntlayerConfig = {
      // ... Інша частина вашої конфігурації
      compiler: {
        /**
         * Вказує, чи повинен бути включений компілятор.
         */
        enabled: true,
    
        /**
         * Визначає шлях до вихідних файлів
         */
        output: ({ fileName, extension }) => `./${fileName}${extension}`,
    
        /**
         * Вказує, чи повинні компоненти зберігатися після перетворення. Таким чином, компілятор можна запустити лише один раз для перетворення програми, а потім видалити.
         */
        saveComponents: false,
    
        /**
         * Префікс ключа словника
         */
        dictionaryKeyPrefix: "",
      },
    };
    
    export default config;

    Команда витягуванняКомпілятор Babel

    Запустіть екстрактор для перетворення компонентів і витягування вмісту

    bash

    Копіювати вміст

    Копіювати код

    Скопіюйте код у буфер обміну

    npx intlayer extract

    Оновіть свій vite.config.ts, щоб включити плагін intlayerCompiler:

    vite.config.ts

    Копіювати вміст

    Копіювати код

    Скопіюйте код у буфер обміну

    import { defineConfig } from "vite";import { intlayer, intlayerCompiler } from "vite-intlayer";export default defineConfig({ plugins: [   intlayer(),   intlayerCompiler(), // Додає плагін компілятора ],});

    bash

    Копіювати вміст

    Копіювати код

    Скопіюйте код у буфер обміну

    npm run build # Або npm run dev

Налаштування Git

Рекомендується ігнорувати файли, згенеровані Intlayer.

# Ігнорувати файли, згенеровані Intlayer.intlayer

Далі

• Visual Editor: Інтегруйте Intlayer Visual Editor, щоб редагувати переклади безпосередньо з UI.
• CMS: Виносьте керування вмістом назовні, використовуючи Intlayer CMS.