Переведите ваш Vite and Solid с Intlayer | Интернационализация (i18n)

Table of Contents

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

По сравнению с основными решениями, такими как @solid-primitives/i18n или i18next, Intlayer — это решение со встроенными оптимизациями, такими как:

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

Table of Contents

1. 1

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

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

   bash

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

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

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

   npx intlayer init --interactive
   

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

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

   bash

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

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

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

   npm install intlayer solid-intlayer
   npm install vite-intlayer --save-dev
   

   • intlayer

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

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

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

2. 2

   Настройка вашего проекта

   Архитектура

   В этой архитектуре solid-intlayer предоставляет IntlayerProvider, смонтированный в index.tsx для оборачивания дерева Solid. Объявления контента находятся в src/ рядом с компонентами.

   bash

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

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

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

   .
   ├── src
   │   ├── app.content.ts
   │   ├── App.css
   │   ├── App.tsx                       # Main Solid component
   │   ├── index.css
   │   ├── index.tsx                     # Entry point with IntlayerProvider
   │   └── vite-env.d.ts
   ├── index.html
   ├── intlayer.config.ts
   ├── package.json
   ├── tsconfig.json
   └── vite.config.ts
   

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

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

   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, перенаправление в промежуточном ПО, имена cookie, расположение и расширение ваших деклараций контента, отключить логи Intlayer в консоли и многое другое. Для полного списка доступных параметров обратитесь к документации по конфигурации.

3. 3

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

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

   vite.config.ts

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

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

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

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

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

4. 4

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

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

   src/app.content.tsx

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

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

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

   import { t, type Dictionary } from "intlayer";
   
   const appContent = {
     key: "app",
     content: {},
   } satisfies Dictionary;
   
   export default appContent;
   

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

5. 5

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

   Получите доступ к вашим словарям контента во всем приложении:

   src/App.tsx

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

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

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

   import { createSignal, type Component } from "solid-js";
   import solidLogo from "./assets/solid.svg";
   import viteLogo from "/vite.svg";
   import "./App.css";
   import { IntlayerProvider, useIntlayer } from "solid-intlayer";
   
   const AppContent: Component = () => {
     const [count, setCount] = createSignal(0);
     const content = useIntlayer("app");
   
     return (
       <>
         <div>
           <a href="https://vitejs.dev" target="_blank">
             <img src={viteLogo} class="logo" alt={content.viteLogo.value} />
           </a>
           <a href="https://www.solidjs.com/" target="_blank">
             <img
               src={solidLogo}
               class="logo solid"
               alt={content.solidLogo.value}
             />
           </a>
         </div>
         <h1>{content.title}</h1>
         <div class="card">
           <button onClick={() => setCount((count) => count + 1)}>
             {content.count({ count: count() })}
           </button>
           <p>{content.edit}</p>
         </div>
         <p class="read-the-docs">{content.readTheDocs}</p>
       </>
     );
   };
   
   const App: Component = () => (
     <IntlayerProvider>
       <AppContent />
     </IntlayerProvider>
   );
   
   export default App;
   

   В Solid useIntlayer возвращает функцию accessor (например, `content.). Вы должны вызвать эту функцию для доступа к реактивному контенту.

   Если вы хотите использовать ваш контент в атрибуте string, таком как alt, title, href, aria-label и т.д., вы должны вызвать значение функции, например:

   tsx

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

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

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

   <img src={content.image.src.value} alt={content.image.value} />
   <img src={content.image.src.toString()} alt={content.image.toString()} />
   <img src={String(content.image.src)} alt={String(content.image)} />
   

6. 6

   Изменение языка вашего контента

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

   Чтобы изменить язык вашего контента, вы можете использовать функцию setLocale, предоставляемую хуком useLocale. Эта функция позволяет установить локаль приложения и обновить контент соответственно.

   src/components/LocaleSwitcher.tsx

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

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

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

   import { type Component, For } from "solid-js";
   import { Locales } from "intlayer";
   import { useLocale } from "solid-intlayer";
   
   const LocaleSwitcher: Component = () => {
     const { locale, setLocale, availableLocales } = useLocale();
   
     return (
       <select
         value={locale()}
         onChange={(e) => setLocale(e.currentTarget.value as Locales)}
       >
         <For each={availableLocales}>
           {(loc) => (
             <option value={loc} selected={loc === locale()}>
               {loc}
             </option>
           )}
         </For>
       </select>
     );
   };
   

7. 7

   Добавление локализованной маршрутизации в ваше приложение

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

   Цель этого шага - создать уникальные маршруты для каждого языка. Это полезно для SEO и SEO-дружественных URL. Пример:

   plaintext

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

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

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

   - https://example.com/about
   - https://example.com/es/about
   - https://example.com/fr/about
   

   Чтобы добавить локализованную маршрутизацию в ваше приложение, вы можете использовать @solidjs/router.

   Сначала установите необходимые зависимости:

   bash

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

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

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

   npm install @solidjs/router
   

   Затем оберните ваше приложение в Router и определите ваши маршруты, используя localeMap:

   src/index.tsx

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

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

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

   import { render } from "solid-js/web";
   import { Router } from "@solidjs/router";
   import App from "./App";
   
   const root = document.getElementById("root");
   
   render(
     () => (
       <Router>
         <App />
       </Router>
     ),
     root!
   );
   

   src/App.tsx

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

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

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

   import { type Component } from "solid-js";
   import { Route } from "@solidjs/router";
   import { localeMap } from "intlayer";
   import { IntlayerProvider } from "solid-intlayer";
   import Home from "./pages/Home";
   import About from "./pages/About";
   
   const App: Component = () => (
     <IntlayerProvider>
       {localeMap(({ locale, urlPrefix }) => (
         <Route
           path={urlPrefix || "/"}
           component={(props: any) => (
             <IntlayerProvider locale={locale}>{props.children}</IntlayerProvider>
           )}
         >
           <Route path="/" component={Home} />
           <Route path="/about" component={About} />
         </Route>
       ))}
     </IntlayerProvider>
   );
   
   export default App;
   

8. 8

   Изменение URL при смене локали

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

   Чтобы изменить URL при смене локали, вы можете использовать проп onLocaleChange, предоставляемый хуком useLocale. Вы можете использовать хуки useNavigate и useLocation из @solidjs/router для обновления пути URL.

   src/components/LocaleSwitcher.tsx

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

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

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

   import { type Component, For } from "solid-js";
   import { useLocation, useNavigate } from "@solidjs/router";
   import { getLocalizedUrl } from "intlayer";
   import { useLocale } from "solid-intlayer";
   
   const LocaleSwitcher: Component = () => {
     const location = useLocation();
     const navigate = useNavigate();
     const { locale, setLocale, availableLocales } = useLocale({
       onLocaleChange: (loc) => {
         const pathWithLocale = getLocalizedUrl(location.pathname, loc);
         navigate(pathWithLocale);
       },
     });
   
     return (
       <select
         value={locale()}
         onChange={(e) => setLocale(e.currentTarget.value as any)}
       >
         <For each={availableLocales}>
           {(loc) => (
             <option value={loc} selected={loc === locale()}>
               {loc}
             </option>
           )}
         </For>
       </select>
     );
   };
   

9. 9

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

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

   Обновите атрибуты lang и dir тега <html>, чтобы они соответствовали текущей локали для доступности и SEO.

   src/App.tsx

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

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

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

   import { createEffect, type Component } from "solid-js";
   import { useLocale } from "solid-intlayer";
   import { getHTMLTextDir } from "intlayer";
   
   const AppContent: Component = () => {
     const { locale } = useLocale();
   
     createEffect(() => {
       document.documentElement.lang = locale();
       document.documentElement.dir = getHTMLTextDir(locale());
     });
   
     return (
       // ... Содержимое вашего приложения
     );
   };
   

10. 10

    Создание локализованного компонента ссылки

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

    Создайте пользовательский компонент Link, который автоматически добавляет префикс внутренних URL с текущим языком.

    src/components/Link.tsx

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

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

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

    import { type ParentComponent } from "solid-js";
    import { A, type AnchorProps } from "@solidjs/router";
    import { getLocalizedUrl } from "intlayer";
    import { useLocale } from "solid-intlayer";
    
    export const Link: ParentComponent<AnchorProps> = (props) => {
      const { locale } = useLocale();
    
      const isExternal = () => props.href.startsWith("http");
      const localizedHref = () =>
        isExternal() ? props.href : getLocalizedUrl(props.href, locale());
    
      return <A {...props} href={localizedHref()} />;
    };
    

11. 11

    Рендеринг Markdown

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

    Intlayer поддерживает рендеринг контента Markdown непосредственно в вашем приложении Solid, используя свой собственный внутренний парсер. По умолчанию Markdown обрабатывается как обычный текст. Чтобы отрендерить его как богатый HTML, оберните ваше приложение в MarkdownProvider.

    Затем вы можете использовать его в ваших компонентах:

    tsx

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

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

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

    import { useIntlayer } from "solid-intlayer";
    
    const MyComponent = () => {
      const content = useIntlayer("my-content");
    
      return (
        <div>
          {/* Рендерится как HTML через MarkdownProvider */}
          {content.markdownContent}
        </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
    

    intlayer >= 9intlayer < 9

    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
    

(Опционально) Sitemap и robots.txt (генерация на сборке)

Intlayer предоставляет generateSitemap и getMultilingualUrls - утилиты, которые формируют многоязычные sitemap.xml и robots.txt для краулеров и позволяют автоматически записать их в public/. Обычно запускают небольшой Node-скрипт до Vite (например, npm-хуки predev / prebuild).

Sitemap

Генератор sitemap учитывает локали и добавляет нужные метаданные.

Поддерживается пространство имён xhtml:link (hreflang). Вместо плоского списка URL Intlayer связывает все языковые версии страницы в обе стороны (например /about, /fr/about или /about?lang=fr в зависимости от режима маршрутизации).

Robots.txt

Используйте getMultilingualUrls, чтобы правила Disallow покрывали все локализованные варианты путей.

1. Файл generate-seo.mjs в корне проекта

import fs from "fs";
import path from "path";
import { fileURLToPath } from "url";
import { generateSitemap, getMultilingualUrls } from "intlayer";

const __dirname = path.dirname(fileURLToPath(import.meta.url));

const SITE_URL = (process.env.SITE_URL || "http://localhost:5173").replace(
  /\/$/,
  ""
);

const pathList = [
  { path: "/", changefreq: "daily", priority: 1.0 },
  { path: "/about", changefreq: "monthly", priority: 0.7 },
];

const sitemapXml = generateSitemap(pathList, {
  siteUrl: "https://example.com",
});
fs.writeFileSync(path.join(__dirname, "public", "sitemap.xml"), sitemapXml);

const getAllMultilingualUrls = (urls) =>
  urls.flatMap((url) => Object.values(getMultilingualUrls(url)));

const disallowedPaths = getAllMultilingualUrls(["/admin", "/private"]);

const robotsTxt = [
  "User-agent: *",
  "Allow: /",
  ...disallowedPaths.map((path) => `Disallow: ${path}`),
  "",
  `Sitemap: https://example.com/sitemap.xml`,
].join("\n");

fs.writeFileSync(path.join(__dirname, "public", "robots.txt"), robotsTxt);

console.log("SEO files generated successfully.");

Пакет intlayer должен быть установлен. Для продакшена задайте SITE_URL в окружении (например в CI).

Для Node ESM предпочтительно generate-seo.mjs. Для generate-seo.js укажите "type": "module" в package.json или включите ESM иначе.

2. Запуск скрипта до Vite

{
  "scripts": {
    "dev": "vite",
    "prebuild": "node generate-seo.mjs",
    "build": "vite build",
    "preview": "vite preview"
  }
}

Подстройте команды для pnpm или yarn. Скрипт можно вызывать из CI или другого шага.

Настройка TypeScript

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

{
  "compilerOptions": {
    // ...
  },
  "include": ["src", ".intlayer/**/*.ts"],
}

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

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

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

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

VS Code Extension

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

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

Продвинутые возможности

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

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