Переводите ваш сайт Astro + Vue с помощью Intlayer | Интернационализация (i18n)

Содержание

Почему Intlayer лучше альтернатив?

По сравнению с основными решениями, такими как astro-i18n или i18next, Intlayer представляет собой решение со встроенными оптимизациями, такими как:

Пошаговое руководство по настройке Intlayer в Astro + Vue

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

1. 1

   Установка зависимостей

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

   bash

   Копировать содержимое

   Копировать код

   Копировать код в буфер обмена

   npx intlayer init --interactive
   

   флаг --interactive не является обязательным. Используйте intlayer-cli init, если вы являетесь ИИ-агентом.

   Эта команда определит вашу среду и установит необходимые пакеты. Например:

   bash

   Копировать содержимое

   Копировать код

   Копировать код в буфер обмена

   npm install intlayer astro-intlayer vue vue-intlayer @astrojs/vue
   

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

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

   • vue Основной пакет Vue.

   • vue-intlayer Пакет, который интегрирует Intlayer с приложениями Vue. Он предоставляет installIntlayer, а также композиблы (composables) useIntlayer и useLocale для интернационализации в Vue.

   • @astrojs/vue Официальная интеграция Astro, которая позволяет использовать острова (islands) компонентов Vue.

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;
   

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

3. 3

   Интеграция Intlayer в конфигурацию Astro

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

   astro.config.ts

   Копировать содержимое

   Копировать код

   Копировать код в буфер обмена

   // @ts-check
   
   import { intlayer } from "astro-intlayer";
   import vue from "@astrojs/vue";
   import { defineConfig } from "astro/config";
   
   // https://astro.build/config
   export default defineConfig({
     integrations: [intlayer(), vue()],
   });
   

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

   Интеграция vue() позволяет использовать острова компонентов Vue через client:only="vue".

4. 4

   Объявление контента

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

   src/app.content.ts

   Копировать содержимое

   Копировать код

   Копировать код в буфер обмена

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

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

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

5. 5

   Использование контента в Astro

   Вы можете использовать словари напрямую в файлах .astro, используя основные хелперы, экспортируемые из intlayer. Вам также следует добавить SEO-метаданные, такие как hreflang и канонические ссылки, на каждую страницу и встроить остров Vue для интерактивного контента на стороне клиента.

   src/pages/[...locale]/index.astro

   Копировать содержимое

   Копировать код

   Копировать код в буфер обмена

   ---
   import {
     getIntlayer,
     getLocaleFromPath,
     getLocalizedUrl,
     getHTMLTextDir,
     getPrefix,
     localeMap,
     defaultLocale,
     type LocalesValues,
   } from "intlayer";
   import VueIsland from "../../components/vue/VueIsland.vue";
   
   export const getStaticPaths = () => {
     return localeMap(({ locale }) => ({
       params: { locale: getPrefix(locale).localePrefix },
     }));
   };
   
   const locale = getLocaleFromPath(Astro.url.pathname) as LocalesValues;
   const { title } = getIntlayer("app", locale);
   ---
   
   <!doctype html>
   <html lang={locale} dir={getHTMLTextDir(locale)}>
     <head>
       <meta charset="utf-8" />
       <meta name="viewport" content="width=device-width" />
       <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
       <title>{title}</title>
   
       <!-- Каноническая ссылка: Сообщает поисковым системам, какая версия страницы является основной -->
       <link
         rel="canonical"
         href={new URL(getLocalizedUrl(Astro.url.pathname, locale), Astro.site)}
       />
   
       <!-- Hreflang: Сообщает Google о наличии всех локализованных версий -->
       {
         localeMap(({ locale: mapLocale }) => (
           <link
             rel="alternate"
             hreflang={mapLocale}
             href={new URL(
               getLocalizedUrl(Astro.url.pathname, mapLocale),
               Astro.site
             )}
           />
         ))
       }
   
       <!-- x-default: Резервный вариант для пользователей с несовпадающими языками -->
       <link
         rel="alternate"
         hreflang="x-default"
         href={new URL(
           getLocalizedUrl(Astro.url.pathname, defaultLocale),
           Astro.site
         )}
       />
     </head>
     <body>
       <!-- Остров Vue отрисовывает весь интерактивный контент, включая переключатель языков -->
       <VueIsland locale={locale} client:only="vue" />
     </body>
   </html>
   

   Примечание по конфигурации маршрутизации: Структура каталогов, которую вы используете, зависит от настройки middleware.routing в вашем intlayer.config.ts:

   • prefix-no-default (по умолчанию): Сохраняет локаль по умолчанию в корне (без префикса) и добавляет префиксы к остальным. Используйте [...locale] для обработки всех случаев.
   • prefix-all: Все URL имеют префикс языка. Вы можете использовать стандартный [locale], если вам не нужно обрабатывать корень отдельно.
   • search-param или no-prefix: Папка локали не нужна. Локаль обрабатывается через параметры поиска или куки.

6. 6

   Создание компонента Острова Vue

   Создайте компонент острова, который оборачивает ваше приложение Vue и получает локаль, определенную сервером. Необходимо вызвать installIntlayer, чтобы зарегистрировать плагин Intlayer в экземпляре Vue перед использованием любых композиблов.

   src/components/vue/VueIsland.vue

   Копировать содержимое

   Копировать код

   Копировать код в буфер обмена

   <script setup lang="ts">
   import { ref, getCurrentInstance } from "vue";
   import { useIntlayer, useLocale, installIntlayer } from "vue-intlayer";
   import { getLocalizedUrl, getLocaleName, type LocalesValues } from "intlayer";
   
   const props = defineProps<{ locale: LocalesValues }>();
   
   const app = getCurrentInstance()?.appContext.app;
   if (app) {
     installIntlayer(app, { locale: props.locale });
   }
   
   const {
     locale: currentLocale,
     availableLocales,
     setLocale,
   } = useLocale({
     onLocaleChange: (newLocale: LocalesValues) => {
       window.location.href = getLocalizedUrl(window.location.pathname, newLocale);
     },
   });
   
   const count = ref(0);
   const { title } = useIntlayer("app");
   </script>
   
   <template>
     <div>
       <h1>{{ title }}</h1>
       <!-- Переключатель языка отрисовывается внутри шаблона острова -->
       <div class="locale-switcher">
         <span class="switcher-label">Сменить язык:</span>
         <div class="locale-buttons">
           <button
             v-for="localeItem in availableLocales"
             :key="localeItem"
             :class="['locale-btn', { active: localeItem === currentLocale }]"
             :disabled="localeItem === currentLocale"
             @click="setLocale(localeItem)"
           >
             <span class="ls-own-name">{{ getLocaleName(localeItem) }}</span>
             <span class="ls-current-name">{{
               getLocaleName(localeItem, currentLocale)
             }}</span>
             <span class="ls-code">{{ localeItem.toUpperCase() }}</span>
           </button>
         </div>
       </div>
     </div>
   </template>
   

   Проп locale передается со страницы Astro (определенной сервером) и используется для инициализации installIntlayer, что делает её локалью по умолчанию для всех композиблов в дереве компонентов.

7. 7

   Добавление переключателя языков

   Переключатель языков встроен непосредственно в шаблон острова Vue (показано в Шаге 6). Он использует useLocale из vue-intlayer и переходит по локализованному URL, когда пользователь выбирает новый язык:

   src/components/vue/VueIsland.vue

   Копировать содержимое

   Копировать код

   Копировать код в буфер обмена

   <script setup lang="ts">
   import { useLocale } from "vue-intlayer";
   import { getLocalizedUrl, getLocaleName, type LocalesValues } from "intlayer";
   
   // Используется та же настройка props/app, что и в Шаге 6 выше...
   
   const {
     locale: currentLocale,
     availableLocales,
     setLocale,
   } = useLocale({
     onLocaleChange: (newLocale: LocalesValues) => {
       // Перейти по локализованному URL при смене языка
       window.location.href = getLocalizedUrl(window.location.pathname, newLocale);
     },
   });
   </script>
   
   <template>
     <div class="locale-switcher">
       <span class="switcher-label">Сменить язык:</span>
       <div class="locale-buttons">
         <button
           v-for="localeItem in availableLocales"
           :key="localeItem"
           :class="['locale-btn', { active: localeItem === currentLocale }]"
           :disabled="localeItem === currentLocale"
           @click="setLocale(localeItem)"
         >
           <span class="ls-own-name">{{ getLocaleName(localeItem) }}</span>
           <span class="ls-current-name">{{
             getLocaleName(localeItem, currentLocale)
           }}</span>
           <span class="ls-code">{{ localeItem.toUpperCase() }}</span>
         </button>
       </div>
     </div>
   </template>
   

   Примечание по сохранению состояния: Использование onLocaleChange для перенаправления через window.location.href гарантирует посещение нового языкового URL, позволяя middleware Intlayer установить куки языка и запомнить предпочтение пользователя для будущих посещений.

8. 8

   Sitemap и Robots.txt

   Intlayer предоставляет утилиты для динамического создания локализованных карт сайта и файлов robots.txt.

   Sitemap

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

   Создаваемая Intlayer карта сайта поддерживает пространство имен xhtml:link (Hreflang XML Extensions). В отличие от стандартных генераторов карт сайта, которые просто перечисляют прямые URL-адреса, Intlayer автоматически создает необходимые двусторонние связи между всеми языковыми версиями страницы (например, /about, /about?lang=fr и /about?lang=es). Это гарантирует, что поисковые системы будут правильно индексировать и показывать нужную языковую версию соответствующей аудитории.

   Создайте src/pages/sitemap.xml.ts для генерации карты сайта, включающей все ваши локализованные маршруты.

   src/pages/sitemap.xml.ts

   Копировать содержимое

   Копировать код

   Копировать код в буфер обмена

   import type { APIRoute } from "astro";
   import { generateSitemap, type SitemapUrlEntry } from "intlayer";
   
   const pathList: SitemapUrlEntry[] = [
     { path: "/", changefreq: "daily", priority: 1.0 },
     { path: "/about", changefreq: "monthly", priority: 0.7 },
   ];
   
   const SITE_URL = import.meta.env.SITE ?? "http://localhost:4321";
   
   export const GET: APIRoute = async ({ site }) => {
     const xmlOutput = generateSitemap(pathList, { siteUrl: SITE_URL });
   
     return new Response(xmlOutput, {
       headers: { "Content-Type": "application/xml" },
     });
   };
   

   Robots.txt

   Создайте src/pages/robots.txt.ts для управления сканированием поисковыми системами.

   src/pages/robots.txt.ts

   Копировать содержимое

   Копировать код

   Копировать код в буфер обмена

   import type { APIRoute } from "astro";
   import { getMultilingualUrls } from "intlayer";
   
   const getAllMultilingualUrls = (urls: string[]) =>
     urls.flatMap((url) => Object.values(getMultilingualUrls(url)) as string[]);
   
   const disallowedPaths = getAllMultilingualUrls(["/admin", "/private"]);
   
   export const GET: APIRoute = ({ site }) => {
     const robotsTxt = [
       "User-agent: *",
       "Allow: /",
       ...disallowedPaths.map((path) => `Disallow: ${path}`),
       "",
       `Sitemap: ${new URL("/sitemap.xml", site).href}`,
     ].join("\n");
   
     return new Response(robotsTxt, {
       headers: { "Content-Type": "text/plain" },
     });
   };
   

9. 15

   Извлечение содержимого ваших компонентов

   Необязательно

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

   Чтобы упростить этот процесс, 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
   

   Since v9, the intlayerCompiler is included in the intlayer plugin. So you don't need to add it manually.

   Обновите ваш vite.config.ts, чтобы включить плагин intlayerCompiler:

   vite.config.ts

   Копировать содержимое

   Копировать код

   Копировать код в буфер обмена

   import { defineConfig } from "vite";
   import { intlayer, intlayerCompiler } from "vite-intlayer";
   
   export default defineConfig({
     plugins: [
       intlayer(),
       intlayerCompiler(), // Adds the compiler plugin
     ],
   });
   

   bash

   Копировать содержимое

   Копировать код

   Копировать код в буфер обмена

   npm run build # Или npm run dev
   

Настройка TypeScript

Intlayer использует расширение модулей, чтобы воспользоваться преимуществами TypeScript и сделать вашу кодовую базу более надежной.

Убедитесь, что ваша конфигурация TypeScript включает автогенерируемые типы.

{
  // ... Ваши существующие конфигурации TypeScript
  include: [
    // ... Ваши существующие конфигурации TypeScript
    ".intlayer/**/*.ts", // Включить автогенерируемые типы
  ],
}

Настройка Git

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

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

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

Расширение для VS Code

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

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

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

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

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

Дальнейшие шаги

Вы также можете внедрить визуальный редактор или вынести ваш контент во внешнюю CMS.

Часто задаваемые вопросы