@intlayer/docs 9.3.3 → 9.4.0

package/docs/ru/intlayer_with_tanstack+solid.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2025-03-25
-updatedAt: 2026-06-23
+updatedAt: 2026-08-25
 title: "TanStack Start + Solid i18n - Полное руководство по переводу вашего приложения"
 description: "Больше никакого i18next. Руководство 2026 по созданию многоязычного (i18n) приложения TanStack Start + Solid. Переводите с помощью ИИ-агентов и оптимизируйте размер бандла, SEO и производительность."
 keywords:
@@ -22,6 +22,9 @@ applicationTemplate: https://github.com/aymericzip/intlayer-tanstack-start-solid
 applicationShowcase: https://intlayer-tanstack-start-solid.vercel.app
 youtubeVideo: https://www.youtube.com/watch?v=_XTdKVWaeqg
 history:
+  - version: 9.4.0
+    date: 2026-08-25
+    changes: "Сравнение статического, динамического и кэшированного динамического разрешения словарей метаданных в функциях head маршрутов"
   - version: 8.9.0
     date: 2026-05-04
     changes: "Обновление использования API useIntlayer в Solid для прямого доступа к свойствам"
@@ -41,7 +44,7 @@ author: aymericzip
 
 ## Почему Intlayer лучше альтернатив?
 
-По сравнению с основными решениями, такими как «react-i18next» или «i18next», Intlayer — это решение, которое включает в себя встроенные оптимизации, такие как:
+По сравнению с основными решениями, такими как «react-i18next» или «i18next», Intlayer предлагает решение, которое включает в себя встроенные оптимизации, такие как:
 
 <AccordionGroup>
 
@@ -65,7 +68,7 @@ Intlayer оптимизирован для идеальной работы с Ta
 
 <Accordion header="Агент ИИ">
 
-Совместное размещение контента **уменьшает контекст, необходимый** для моделей большого языка (LLM). Intlayer также поставляется с набором инструментов, таких как **CLI** для проверки отсутствия переводов,**[LSP](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/lsp.md)**, **[MCP](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/mcp_server.md)**, и **[навыки агента](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/agent_skills.md)**, чтобы сделать работу разработчика (DX) еще более удобной для агентов ИИ.
+Совместное размещение контента **уменьшает контекст, необходимый** для моделей большого языка (LLM). Intlayer также поставляется с набором инструментов, таких как **CLI** для проверки отсутствия переводов,**[LSP](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/lsp.md)**, **[MCP](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/mcp_server.md)**, и **[agent skills](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ru/agent_skills.md)**, чтобы сделать работу разработчика (DX) еще более удобной для агентов ИИ.
 
 </Accordion>
 
@@ -83,7 +86,7 @@ Intlayer оптимизирован для идеальной работы с Ta
 
 <Accordion header="Масштабирование с помощью не-разработчиками">
 
-Intlayer — это больше, чем просто решение i18n. Он предоставляет **автономный [визуальный редактор](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_visual_editor.md)** и **[полный CMS](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_CMS.md)**, чтобы помочь вам управлять многоязычным контентом в **реальном времени**, упрощая сотрудничество с переводчиками, копирайтерами и другими членами команды. Контент может храниться локально и/или удаленно.
+Intlayer предлагает больше, чем просто решение i18n. Он предоставляет **автономный [визуальный редактор](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_visual_editor.md)** и **[полный CMS](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_CMS.md)**, чтобы помочь вам управлять многоязычным контентом в **реальном времени**, упрощая сотрудничество с переводчиками, копирайтерами и другими членами команды. Контент может храниться локально и/или удаленно.
 
 </Accordion>
 </AccordionGroup>
@@ -458,6 +461,8 @@ export const useLocalizedNavigate = () => {
 
 <Step number={9} title="Использование Intlayer на ваших страницах">
 
+> Используйте **`useIntlayer`** по умолчанию: это рекомендуемый способ читать контент внутри компонентов, и компилятор разрешает его в отрисовываемую локаль. Обращайтесь к `getIntlayer` / `getIntlayerAsync` только вне дерева Solid: в `head` маршрутов, загрузчиках и серверных функциях.
+
 Получайте доступ к вашим словарям контента во всем приложении:
 
 #### Локализованная домашняя страница
@@ -487,8 +492,6 @@ function RouteComponent() {
 }
 ```
 
-> Если вы хотите использовать ваш контент в атрибуте типа `string`, таком как `alt`, `title`, `href`, `aria-label` и т.д., вы должны вызвать значение функции, например:
-
 > ```html
 > <img src="{content.image.src.value}" alt="{content.image.value}" />
 > <img src="{content.image.src.toString()}" alt="{content.image.toString()}" />
@@ -574,6 +577,8 @@ const RootComponent: ParentComponent = (props) => {
 
 > Обратите внимание, что для использования `intlayerProxy` в режиме production вам необходимо перенести пакет `vite-intlayer` из `devDependencies` в `dependencies`.
 
+> Начиная с Intlayer v9, `intlayerProxy()` встроен непосредственно в плагин `intlayer()` и включен по умолчанию через параметр `routing.enableProxy` (`true` по умолчанию). Регистрация его отдельно, как показано ниже, теперь опциональна: она сохранена для обратной совместимости и для конфигураций, которым нужно контролировать порядок плагинов. Установите `routing.enableProxy: false`, чтобы отключить эту функцию. См. [примечания к выпуску v9](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ru/releases/v9.md).
+
 ```typescript fileName="vite.config.ts"
 import { tanstackStart } from "@tanstack/solid-start/plugin/vite";
 import solid from "vite-plugin-solid";
@@ -606,16 +611,25 @@ export default defineConfig({
 
 <Step number={13} title="Интернационализация ваших метаданных">
 
-Вы также можете использовать функцию `getIntlayer` для доступа к вашим словарям контента внутри загрузчика `head` для метаданных с учетом локали:
+<Tabs>
+
+<Tab label="Статическое разрешение" value="static">
+
+`getIntlayer` разрешается синхронно по **объединённому** словарю, то есть тому, который содержит все объявленные локали. `head` остаётся синхронным, ничего не ожидается, но весь многоязычный словарь попадает в чанк маршрута, отправляемый в браузер.
 
 ```tsx fileName="src/routes/{-$locale}/index.tsx"
 import { createFileRoute } from "@tanstack/solid-router";
-import { getIntlayer } from "intlayer";
+import {
+  defaultLocale,
+  getIntlayer,
+  getLocalizedUrl,
+  localeMap,
+} from "intlayer";
 
 export const Route = createFileRoute("/{-$locale}/")({
   component: RouteComponent,
   head: ({ params }) => {
-    const { locale } = params;
+    const { locale = defaultLocale } = params;
     const path = "/"; // The path for this route
 
     const metaContent = getIntlayer("app", locale);
@@ -649,6 +663,143 @@ export const Route = createFileRoute("/{-$locale}/")({
 });
 ```
 
+Подходит для небольших словарей метаданных, малого числа локалей или на этапе прототипирования.
+
+</Tab>
+
+<Tab label="Динамическое разрешение" value="dynamic">
+
+`getIntlayerAsync` (доступен начиная с **v9.4**) ведёт себя как `getIntlayer`, но плагин сборки направляет его на пер-локальный чанк в `.intlayer/dynamic_dictionaries/` вместо объединённого словаря. Поэтому страница отдаёт только ту локаль, которую рендерит. Так как этот чанк загружается по требованию, `head` становится `async`:
+
+```tsx fileName="src/routes/{-$locale}/index.tsx"
+import { createFileRoute } from "@tanstack/solid-router";
+import {
+  defaultLocale,
+  getIntlayerAsync,
+  getLocalizedUrl,
+  localeMap,
+} from "intlayer";
+
+export const Route = createFileRoute("/{-$locale}/")({
+  component: RouteComponent,
+  head: async ({ params }) => {
+    const { locale = defaultLocale } = params;
+    const path = "/"; // The path for this route
+
+    const metaContent = await getIntlayerAsync("app", locale);
+
+    return {
+      links: [
+        // Canonical link: Points to the current localized page
+        { rel: "canonical", href: getLocalizedUrl(path, locale) },
+
+        // Hreflang: Tell Google about all localized versions
+        ...localeMap(({ locale: mapLocale }) => ({
+          rel: "alternate",
+          hrefLang: mapLocale,
+          href: getLocalizedUrl(path, mapLocale),
+        })),
+
+        // x-default: For users in unmatched languages
+        // Define the default fallback locale (usually your primary language)
+        {
+          rel: "alternate",
+          hrefLang: "x-default",
+          href: getLocalizedUrl(path, defaultLocale),
+        },
+      ],
+      meta: [
+        { title: metaContent.title },
+        { name: "description", content: metaContent.meta.description },
+      ],
+    };
+  },
+});
+```
+
+> Если `head` читает несколько словарей, разрешайте их через `Promise.all`: ожидание каждого `getIntlayerAsync` отдельной строкой выстраивает запросы в цепочку вместо параллельного выполнения.
+
+Компромисс: динамический импорт разрешается во время выполнения `head`, на критическом пути рендеринга документа. На «холодном» маршруте это задерживает `head` на несколько миллисекунд и может немного ухудшить **LCP**.
+
+</Tab>
+
+<Tab label="Кэшированное динамическое разрешение" value="cached">
+
+Разрешите словарь в `loader` маршрута и прочитайте его обратно из `loaderData` в `head`. Загрузчики совпавших маршрутов выполняются параллельно, а `staleTime: Infinity` сообщает TanStack Router, что результат никогда не устаревает, поэтому пер-локальный чанк разрешается один раз, а затем отдаётся из кэша роутера, оставляя `head` синхронным.
+
+```tsx fileName="src/routes/{-$locale}/index.tsx"
+import { createFileRoute } from "@tanstack/solid-router";
+import {
+  defaultLocale,
+  getIntlayerAsync,
+  getLocalizedUrl,
+  localeMap,
+} from "intlayer";
+
+export const Route = createFileRoute("/{-$locale}/")({
+  component: RouteComponent,
+  // Resolved in parallel with the other matched routes, off the head critical path
+  loader: async ({ params }) => {
+    const { locale = defaultLocale } = params;
+
+    return { metaContent: await getIntlayerAsync("app", locale) };
+  },
+  // The dictionary never changes for a given locale: resolve the chunk once
+  staleTime: Infinity,
+  head: ({ params, loaderData }) => {
+    const { locale = defaultLocale } = params;
+    const path = "/"; // The path for this route
+
+    return {
+      links: [
+        // Canonical link: Points to the current localized page
+        { rel: "canonical", href: getLocalizedUrl(path, locale) },
+
+        // Hreflang: Tell Google about all localized versions
+        ...localeMap(({ locale: mapLocale }) => ({
+          rel: "alternate",
+          hrefLang: mapLocale,
+          href: getLocalizedUrl(path, mapLocale),
+        })),
+
+        // x-default: For users in unmatched languages
+        // Define the default fallback locale (usually your primary language)
+        {
+          rel: "alternate",
+          hrefLang: "x-default",
+          href: getLocalizedUrl(path, defaultLocale),
+        },
+      ],
+      meta: [
+        { title: loaderData?.metaContent.title },
+        {
+          name: "description",
+          content: loaderData?.metaContent.meta.description,
+        },
+      ],
+    };
+  },
+});
+```
+
+> `head` может быть вызван до того, как загрузчик завершится, поэтому `loaderData` типизирован как возможно `undefined`. Сохраните опциональную цепочку либо возвращайте запасной заголовок.
+
+Вы сохраняете пер-локальный чанк, не оплачивая его стоимость на критическом пути `head`. Платой становится DX: контент приходится явно прокидывать из загрузчика в `head` через `loaderData`.
+
+</Tab>
+
+</Tabs>
+
+### Какое разрешение выбрать?
+
+|                     | Статическое разрешение | Динамическое разрешение                  | Кэшированное динамическое разрешение     |
+| ------------------- | ---------------------- | ---------------------------------------- | ---------------------------------------- |
+| API                 | `getIntlayer`          | `getIntlayerAsync` (v9.4+)               | `getIntlayerAsync` в `loader` (v9.4+)    |
+| Сигнатура `head`    | синхронная             | `async`                                  | синхронная, читает `loaderData`          |
+| Отправляемые локали | все объявленные локали | только запрошенная локаль                | только запрошенная локаль                |
+| Клиентские переходы | разрешать нечего       | выполняется заново при каждом совпадении | отдаётся из кэша роутера                 |
+| DX                  | самый простой          | один `await`                             | контент прокидывается через `loaderData` |
+
 ---
 
 </Step>