@intlayer/docs 9.4.0-canary.0 → 9.4.1

package/docs/pt/intlayer_with_solid_start.md

@@ -44,6 +44,18 @@ author: aymericzip
 />
 
   </Tab>
+
+  <Tab label="Demo" value="demo">
+
+<iframe
+  src="https://intlayer-solid-start-template.vercel.app"
+  className="m-auto overflow-hidden rounded-lg border-0 max-md:size-full max-md:h-[700px] md:aspect-16/9 md:w-full"
+  title="Demo Intlayer Solid Start Template"
+  sandbox="allow-forms allow-modals allow-popups allow-presentation allow-same-origin allow-scripts"
+  loading="lazy"
+/>
+
+  </Tab>
 </Tabs>
 
 ## Índice

package/docs/pt/intlayer_with_svelte_kit.md

@@ -113,6 +113,8 @@ Mais do que apenas uma solução i18n, o Intlayer fornece um **[editor visual] a
 
 ## Guia Passo a Passo para Configurar o Intlayer em uma Aplicação SvelteKit
 
+Veja [Application Template](https://github.com/aymericzip/intlayer-sveltekit-template) no GitHub.
+
 Para começar, crie um novo projeto SvelteKit. Aqui está a estrutura final que iremos criar:
 
 ```bash
@@ -267,6 +269,8 @@ export default heroContent;
 
 <Step number={5} title="Utilize o Intlayer em Seus Componentes">
 
+Agora você pode usar a função `useIntlayer` em qualquer componente Svelte. Ela retorna um store reativo que se atualiza automaticamente quando a localidade muda. A função respeitará automaticamente a localidade atual (tanto durante SSR quanto na navegação no lado do cliente).
+
 para acessar seu valor reativo (por exemplo, `$content.title`).
 
 ```svelte fileName="src/lib/components/Component.svelte"
@@ -612,6 +616,8 @@ Para permitir que os usuários mudem de idioma, atualize a URL.
 
 Para adicionar um proxy backend à sua aplicação SvelteKit, você pode usar a função `intlayerProxy` fornecida pelo plugin `vite-intlayer`. Este plugin detectará automaticamente a melhor localidade para o usuário com base na URL, cookies e preferências de idioma do navegador.
 
+> Desde o Intlayer v9, `intlayerProxy()` está agrupado diretamente no plugin `intlayer()` e habilitado por padrão através da opção `routing.enableProxy` (`true` por padrão). Registrá-lo separadamente, como mostrado abaixo, agora é opcional — é mantido para compatibilidade retroativa e para configurações que precisam controlar a ordem dos plugins. Configure `routing.enableProxy: false` para desativar. Consulte as [notas de lançamento da v9](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/releases/v9.md).
+
 ```ts fileName="vite.config.ts"
 import { defineConfig } from "vite";
 import { intlayer } from "vite-intlayer";

package/docs/pt/intlayer_with_tanstack+solid.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2025-03-25
-updatedAt: 2026-05-31
+updatedAt: 2026-08-25
 title: "TanStack Start + Solid i18n - Guia completo para traduzir seu aplicativo"
 description: "Sem mais i18next. O guia 2026 para criar uma aplicação TanStack Start + Solid multilíngue (i18n). Traduza com agentes de IA e otimize o tamanho do bundle, SEO e desempenho."
 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: "Comparar a resolução estática, dinâmica e dinâmica em cache dos dicionários de metadados nas funções head das rotas"
   - version: 8.9.0
     date: 2026-05-04
     changes: "Atualizar o uso da API useIntlayer do Solid para acesso direto a propriedades"
@@ -458,6 +461,8 @@ export const useLocalizedNavigate = () => {
 
 <Step number={9} title="Utilizar o Intlayer em Suas Páginas">
 
+> Use **`useIntlayer`** por padrão: é a forma recomendada de ler conteúdo dentro dos componentes, e o compilador o resolve para a localidade que está sendo renderizada. Recorra a `getIntlayer` / `getIntlayerAsync` apenas fora da árvore Solid: o `head` das rotas, os loaders e as server functions.
+
 Acesse seus dicionários de conteúdo através da sua aplicação:
 
 #### Página Inicial Localizada
@@ -487,8 +492,6 @@ function RouteComponent() {
 }
 ```
 
-> Se você quiser usar seu conteúdo em um atributo do tipo `string`, como `alt`, `title`, `href`, `aria-label`, etc., você deve chamar o valor da função, assim:
-
 > ```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 @@ Você também pode usar o `intlayerProxy` para adicionar roteamento do lado do s
 
 > Note que para usar o `intlayerProxy` em produção, você precisa trocar o pacote `vite-intlayer` de `devDependencies` para `dependencies`.
 
+> Desde Intlayer v9, `intlayerProxy()` é agrupado diretamente no plugin `intlayer()` e ativado por padrão através da opção `routing.enableProxy` (`true` por padrão). Registrá-lo separadamente conforme mostrado abaixo agora é opcional: é mantido para compatibilidade com versões anteriores e para configurações que precisam controlar a ordem dos plugins. Defina `routing.enableProxy: false` para recusar. Consulte as [notas de lançamento da v9](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/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="Internacionalizar Seus Metadados">
 
-Você também pode usar a função `getIntlayer` para acessar seus dicionários de conteúdo dentro do loader `head` para metadados cientes de localidade:
+<Tabs>
+
+<Tab label="Resolução estática" value="static">
+
+`getIntlayer` resolve de forma síncrona contra o dicionário **mesclado**, aquele que contém todas as localidades declaradas. O `head` continua síncrono e nada é aguardado, mas todo o dicionário multilíngue é incluído no chunk da rota enviado ao navegador.
 
 ```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}/")({
 });
 ```
 
+Ideal para dicionários de metadados pequenos, poucas localidades ou durante a prototipagem.
+
+</Tab>
+
+<Tab label="Resolução dinâmica" value="dynamic">
+
+`getIntlayerAsync` (disponível a partir da **v9.4**) se comporta como `getIntlayer`, mas o plugin de build o aponta para o chunk por localidade em `.intlayer/dynamic_dictionaries/` em vez do dicionário mesclado. Assim, uma página envia apenas a localidade que renderiza. Como esse chunk é carregado sob demanda, o `head` passa a ser `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 },
+      ],
+    };
+  },
+});
+```
+
+> Se um `head` lê vários dicionários, resolva-os com `Promise.all`: aguardar cada `getIntlayerAsync` em sua própria linha encadeia as requisições em vez de executá-las em paralelo.
+
+O contraponto: o import dinâmico é resolvido enquanto o `head` executa, no caminho crítico da renderização do documento. Numa rota fria isso atrasa o `head` em alguns milissegundos e pode degradar levemente o **LCP**.
+
+</Tab>
+
+<Tab label="Resolução dinâmica em cache" value="cached">
+
+Resolva o dicionário no `loader` da rota e leia-o de volta a partir de `loaderData` no `head`. Os loaders das rotas correspondentes rodam em paralelo, e `staleTime: Infinity` informa ao TanStack Router que o resultado nunca expira, então o chunk por localidade é resolvido uma única vez e depois servido do cache do router, mantendo o `head` síncrono.
+
+```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,
+        },
+      ],
+    };
+  },
+});
+```
+
+> O `head` pode ser chamado antes de o loader resolver, então `loaderData` é tipado como possivelmente `undefined`. Mantenha o encadeamento opcional ou retorne um título de fallback.
+
+Você mantém o chunk por localidade sem pagar seu custo no caminho crítico do `head`. O preço é a experiência de desenvolvimento: o conteúdo precisa ser repassado explicitamente do loader para o `head` via `loaderData`.
+
+</Tab>
+
+</Tabs>
+
+### Qual resolução escolher?
+
+|                                | Resolução estática              | Resolução dinâmica                 | Resolução dinâmica em cache            |
+| ------------------------------ | ------------------------------- | ---------------------------------- | -------------------------------------- |
+| API                            | `getIntlayer`                   | `getIntlayerAsync` (v9.4+)         | `getIntlayerAsync` no `loader` (v9.4+) |
+| Assinatura do `head`           | síncrona                        | `async`                            | síncrona, lê `loaderData`              |
+| Localidades enviadas           | todas as localidades declaradas | apenas a localidade solicitada     | apenas a localidade solicitada         |
+| Navegações no cliente          | nada a resolver                 | reexecutado a cada correspondência | servido do cache do router             |
+| Experiência de desenvolvimento | a mais simples                  | um único `await`                   | conteúdo repassado via `loaderData`    |
+
 ---
 
 </Step>