Задайте питання та отримайте підсумок документа, вказавши цю сторінку та обраного вами постачальника штучного інтелекту
Історія версій
- "Оновлення використання API useIntlayer у Solid для прямого доступу до властивостей"v8.9.004.05.2026
- "Додано команду init"v7.5.930.12.2025
- "Ініціалізація історії"v7.1.1020.11.2025
Вміст цієї сторінки перекладено за допомогою штучного інтелекту.
Переглянути останню версію оригінального вмісту англійськоюIf you have an idea for improving this documentation, please feel free to contribute by submitting a pull request on GitHub.
GitHub link to the documentationCopy doc Markdown to clipboard
Перекладіть свій сайт на SvelteKit із Intlayer | Інтернаціоналізація (i18n)
Зміст
Що таке Intlayer?
Intlayer, інноваційна, відкрита бібліотека для інтернаціоналізації (i18n), створена для спрощення підтримки кількох мов у сучасних вебзастосунках. Вона безшовно працює з можливостями Server-Side Rendering (SSR) у SvelteKit.
За допомогою Intlayer ви можете:
- Легко керувати перекладами, використовуючи декларативні словники на рівні компонентів.
- Динамічно локалізувати метадані, маршрути та вміст.
- Забезпечити підтримку TypeScript за допомогою автогенерованих типів.
- Використовувати SSR SvelteKit для SEO‑дружньої інтернаціоналізації.
Покроковий посібник із налаштування 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: Встановлення залежностей
Встановіть необхідні пакети за допомогою npm:
Скопіюйте код у буфер обміну
npm install intlayer svelte-intlayernpm install vite-intlayer --save-devnpx intlayer init- intlayer: Основний пакет i18n.
- svelte-intlayer: Надає провайдери контексту та stores для Svelte/SvelteKit.
- vite-intlayer: Плагін Vite для інтеграції декларацій контенту в процес збірки.
Крок 2: Налаштування вашого проєкту
Створіть файл конфігурації в корені вашого проєкту:
Скопіюйте код у буфер обміну
import { Locales, type IntlayerConfig } from "intlayer";const config: IntlayerConfig = { internationalization: { locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH], defaultLocale: Locales.ENGLISH, },};export default config;Крок 3: Інтеграція Intlayer у вашу Vite конфігурацію
Оновіть ваш vite.config.ts, щоб додати плагін Intlayer. Цей плагін обробляє транспіляцію ваших файлів вмісту.
Скопіюйте код у буфер обміну
import { sveltekit } from "@sveltejs/kit/vite";import { defineConfig } from "vite";import { intlayer } from "vite-intlayer";export default defineConfig({ plugins: [intlayer(), sveltekit()], // порядок важливий: Intlayer має стояти перед SvelteKit});Крок 4: Оголосіть ваш вміст
Створюйте файли декларацій контенту в будь-якому місці вашої папки src (наприклад, src/lib/content або поруч із компонентами). Ці файли визначають перекладний контент для вашого застосунку, використовуючи функцію t() для кожної локалі.
Крок 5: Використання Intlayer у ваших компонентах
Тепер ви можете використовувати функцію useIntlayer у будь-якому Svelte-компоненті. Вона повертає реактивний store, який автоматично оновлюється при зміні локалі. Функція автоматично враховує поточну локаль (як під час SSR, так і під час навігації на боці клієнта).
Примітка:useIntlayerповертає Svelte-store, тому потрібно використовувати префікс$для доступу до його реактивного значення (наприклад,$content.title).
Скопіюйте код у буфер обміну
<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: Налаштування маршрутизації
Нижче наведено кроки для налаштування маршрутизації на основі локалі в SvelteKit. Це дозволяє додавати префікс локалі до ваших URL (наприклад, /en/about, /fr/about) для кращого SEO та зручності користувача.
Скопіюйте код у буфер обміну
.└─── 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: Обробка визначення локалі на сервері (Hooks)
У SvelteKit сервер повинен знати локаль користувача, щоб відрендерити правильний вміст під час SSR. Ми використовуємо hooks.server.ts для виявлення локалі з URL або cookies.
Створіть або змініть 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), });};Потім створіть допоміжну функцію для отримання локалі користувача з події запиту:
Скопіюйте код у буфер обміну
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, яка перевіряє, чи є локаль валідною:
Скопіюйте код у буфер обміну
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:
Скопіюйте код у буфер обміну
<script lang="ts"> import './layout.css'; let { children } = $props();</script><div class="app"> {@render children()}</div><style> .app { /* */ }</style>Потім створіть нову сторінку та layout у групі [[locale=locale]]:
Скопіюйте код у буфер обміну
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, };};Скопіюйте код у буфер обміну
<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>Скопіюйте код у буфер обміну
export const prerender = true;Скопіюйте код у буфер обміну
<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: Інтернаціоналізовані посилання
Для SEO рекомендується додавати префікс локалі до маршрутів (наприклад, /en/about, /fr/about). Цей компонент автоматично додає префікс поточної локалі до будь-якого посилання.
Скопіюйте код у буфер обміну
<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:
Скопіюйте код у буфер обміну
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: Перемикач мови
Щоб дозволити користувачам переключати мову, оновіть URL.
Скопіюйте код у буфер обміну
<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: Додати backend proxy
Щоб додати backend proxy до вашого застосунку SvelteKit, ви можете використати функцію intlayerProxy, що надається плагіном vite-intlayer. Цей плагін автоматично визначатиме найкращу локаль для користувача на основі URL, cookies та мовних налаштувань браузера.
Скопіюйте код у буфер обміну
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: Налаштування редактора intlayer / CMS
Щоб налаштувати редактор intlayer, дотримуйтесь документації редактора intlayer.
Щоб налаштувати CMS intlayer, дотримуйтесь документації CMS intlayer.
Щоб мати змогу візуалізувати селектор редактора intlayer, потрібно використовувати синтаксис компонента у вашому контенті intlayer.
Скопіюйте код у буфер обміну
<script lang="ts"> import { useIntlayer } from "svelte-intlayer"; const content = useIntlayer("component");</script><div> <!-- Відобразити вміст як простий контент --> <h1>{$content.title}</h1> <!-- Відобразити вміст як компонент (вимагається редактором) --> {@const Component = $content.component}<Component /></div>Налаштування Git
Рекомендується ігнорувати файли, згенеровані Intlayer.
Скопіюйте код у буфер обміну
# Ігнорувати файли, згенеровані Intlayer.intlayer(Необов'язково) Крок 1 : Витягніть вміст ваших компонентів
Якщо у вас є існуюча кодова база, перетворення тисяч файлів може зайняти багато часу.
Щоб спростити цей процес, Intlayer пропонує компілятор / екстрактор для перетворення ваших компонентів і витягування вмісту.
Щоб налаштувати його, ви можете додати розділ compiler у свій файл 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;Запустіть екстрактор для перетворення компонентів і витягування вмісту
Скопіюйте код у буфер обміну
npx intlayer extractДалі
- Visual Editor: Інтегруйте Intlayer Visual Editor, щоб редагувати переклади безпосередньо з UI.
- CMS: Виносьте керування вмістом назовні, використовуючи Intlayer CMS.