@intlayer/docs 9.0.0-canary.3 → 9.0.0-canary.5

package/blog/pt/intlayer_with_next-intl.md

@@ -29,6 +29,10 @@ author: aymericzip
 
 <iframe title="Como automatizar suas traduções JSON do next-intl usando Intlayer" class="m-auto aspect-16/9 w-full overflow-hidden rounded-lg border-0" allow="autoplay; gyroscope;" loading="lazy" width="1080" height="auto" src="https://www.youtube.com/embed/MpGMxniDHNg?autoplay=0&amp;origin=https://intlayer.org&amp;controls=0&amp;rel=1"/>
 
+# Índice
+
+<TOC/>
+
 ## O que é Intlayer?
 
 **Intlayer** é uma biblioteca inovadora e de código aberto para internacionalização, projetada para resolver as limitações das soluções tradicionais de i18n. Ela oferece uma abordagem moderna para o gerenciamento de conteúdo em aplicações Next.js.
@@ -53,28 +57,46 @@ Este guia mostra como aproveitar o sistema superior de declaração de conteúdo
 
 ## Guia passo a passo para configurar o Intlayer com next-intl
 
-### Passo 1: Instalar dependências
+<Steps>
+
+<Step number={1} title="Instalar dependências">
 
 Instale os pacotes necessários:
 
+```bash packageManager="npm"
+npx intlayer-cli init --interactive
+```
+
+```bash packageManager="pnpm"
+pnpm dlx intlayer-cli init --interactive
+```
+
+```bash packageManager="yarn"
+yarn dlx intlayer-cli init --interactive
+```
+
+```bash packageManager="bun"
+bunx intlayer-cli init --interactive
+```
+
+> a flag `--interactive` é opcional. Use `intlayer-cli init` se você for um agente de IA.
+
+> Este comando detectará seu ambiente e instalará os pacotes necessários. Por exemplo:
+
 ```bash packageManager="npm"
 npm install intlayer @intlayer/sync-json-plugin --save-dev
-npx intlayer init
 ```
 
 ```bash packageManager="pnpm"
 pnpm add intlayer @intlayer/sync-json-plugin --save-dev
-pnpm intlayer init
 ```
 
 ```bash packageManager="yarn"
 yarn add intlayer @intlayer/sync-json-plugin --dev
-yarn intlayer init
 ```
 
 ```bash packageManager="bun"
 bun add intlayer @intlayer/sync-json-plugin --dev
-bun x intlayer init
 ```
 
 **Descrição dos pacotes:**
@@ -82,7 +104,9 @@ bun x intlayer init
 - **intlayer**: Biblioteca principal para gerenciamento de internacionalização, declaração de conteúdo e construção
 - **@intlayer/sync-json-plugin**: Plugin para exportar declarações de conteúdo do Intlayer para o formato JSON compatível com next-intl
 
-### Passo 2: Implemente o plugin Intlayer para encapsular o JSON
+</Step>
+
+<Step number={2} title="Implemente o plugin Intlayer para encapsular o JSON">
 
 Crie um arquivo de configuração do Intlayer para definir os locais suportados:
 
@@ -119,7 +143,9 @@ Se alterações forem feitas usando o CLI para traduzir o JSON, ou usando o CMS,
 
 Para ver mais detalhes sobre o plugin `syncJSON`, por favor consulte a [documentação do plugin syncJSON](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/plugins/sync-json.md).
 
-### (Opcional) Passo 3: Implementar traduções JSON por componente
+</Step>
+
+<Step number={3} title="Implementar traduções JSON por componente" isOptional={true}>
 
 Por padrão, o Intlayer carregará, mesclará e sincronizará tanto os arquivos JSON quanto os arquivos de declaração de conteúdo. Veja [a documentação de declaração de conteúdo](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/dictionary/content_file.md) para mais detalhes. Mas, se preferir, usando um plugin do Intlayer, você também pode implementar o gerenciamento por componente de JSON localizado em qualquer lugar da sua base de código.
 
@@ -161,6 +187,10 @@ export default config;
 
 Isso carregará todos os arquivos JSON no diretório `src` que correspondem ao padrão `{key}.i18n.json` e os carregará como dicionários do Intlayer.
 
+</Step>
+
+</Steps>
+
 ## Configuração do Git
 
 É recomendado ignorar os arquivos gerados automaticamente pelo Intlayer:

package/blog/pt/intlayer_with_react-i18next.md

@@ -57,28 +57,46 @@ Este guia mostra como aproveitar o sistema superior de declaração de conteúdo
 
 ## Guia passo a passo para configurar o Intlayer com react-i18next
 
-### Passo 1: Instalar dependências
+<Steps>
+
+<Step number={1} title="Instalar dependências">
 
 Instale os pacotes necessários:
 
+```bash packageManager="npm"
+npx intlayer-cli init --interactive
+```
+
+```bash packageManager="pnpm"
+pnpm dlx intlayer-cli init --interactive
+```
+
+```bash packageManager="yarn"
+yarn dlx intlayer-cli init --interactive
+```
+
+```bash packageManager="bun"
+bunx intlayer-cli init --interactive
+```
+
+> a flag `--interactive` é opcional. Use `intlayer-cli init` se você for um agente de IA.
+
+> Este comando detectará seu ambiente e instalará os pacotes necessários. Por exemplo:
+
 ```bash packageManager="npm"
 npm install intlayer @intlayer/sync-json-plugin --save-dev
-npx intlayer init
 ```
 
 ```bash packageManager="pnpm"
 pnpm add intlayer @intlayer/sync-json-plugin --save-dev
-pnpm intlayer init
 ```
 
 ```bash packageManager="yarn"
 yarn add intlayer @intlayer/sync-json-plugin --dev
-yarn intlayer init
 ```
 
 ```bash packageManager="bun"
 bun add intlayer @intlayer/sync-json-plugin --dev
-bun x intlayer init
 ```
 
 **Descrição dos pacotes:**
@@ -86,7 +104,9 @@ bun x intlayer init
 - **intlayer**: Biblioteca principal para gerenciamento de internacionalização, declaração de conteúdo e construção
 - **@intlayer/sync-json-plugin**: Plugin para exportar declarações de conteúdo do Intlayer para o formato JSON compatível com react-i18next
 
-### Passo 2: Implemente o plugin Intlayer para envolver o JSON
+</Step>
+
+<Step number={2} title="Implemente o plugin Intlayer para envolver o JSON">
 
 Crie um arquivo de configuração do Intlayer para definir os seus locais suportados:
 
@@ -122,7 +142,9 @@ Se alterações forem feitas usando o CLI para traduzir o JSON, ou usando o CMS,
 
 Para ver mais detalhes sobre o plugin `syncJSON`, por favor consulte a [documentação do plugin syncJSON](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/plugins/sync-json.md).
 
-### (Opcional) Passo 3: Implementar traduções JSON por componente
+</Step>
+
+<Step number={3} title="Implementar traduções JSON por componente" isOptional={true}>
 
 Por padrão, o Intlayer irá carregar, mesclar e sincronizar tanto os arquivos JSON quanto os arquivos de declaração de conteúdo. Veja [a documentação da declaração de conteúdo](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/dictionary/content_file.md) para mais detalhes. Mas se preferir, usando um plugin do Intlayer, você também pode implementar o gerenciamento por componente de JSON localizado em qualquer lugar da sua base de código.
 
@@ -163,6 +185,10 @@ export default config;
 
 Isso carregará todos os arquivos JSON no diretório `src` que correspondem ao padrão `{key}.i18n.json` e os carregará como dicionários do Intlayer.
 
+</Step>
+
+</Steps>
+
 ## Configuração do Git
 
 É recomendado ignorar os arquivos gerados automaticamente pelo Intlayer:

package/blog/pt/intlayer_with_react-intl.md

@@ -53,34 +53,48 @@ Embora o Intlayer forneça uma excelente solução i18n independente (veja nosso
 
 Este guia mostra como aproveitar o sistema superior de declaração de conteúdo do Intlayer enquanto mantém a compatibilidade com o react-intl.
 
-## Índice
-
-<TOC/>
-
 ## Guia passo a passo para configurar o Intlayer com react-intl
 
-### Passo 1: Instalar dependências
+<Steps>
+
+<Step number={1} title="Instalar dependências">
 
 Instale os pacotes necessários:
 
+```bash packageManager="npm"
+npx intlayer-cli init --interactive
+```
+
+```bash packageManager="pnpm"
+pnpm dlx intlayer-cli init --interactive
+```
+
+```bash packageManager="yarn"
+yarn dlx intlayer-cli init --interactive
+```
+
+```bash packageManager="bun"
+bunx intlayer-cli init --interactive
+```
+
+> a flag `--interactive` é opcional. Use `intlayer-cli init` se você for um agente de IA.
+
+> Este comando detectará seu ambiente e instalará os pacotes necessários. Por exemplo:
+
 ```bash packageManager="npm"
 npm install intlayer @intlayer/sync-json-plugin --save-dev
-npx intlayer init
 ```
 
 ```bash packageManager="pnpm"
 pnpm add intlayer @intlayer/sync-json-plugin --save-dev
-pnpm intlayer init
 ```
 
 ```bash packageManager="yarn"
 yarn add intlayer @intlayer/sync-json-plugin --dev
-yarn intlayer init
 ```
 
 ```bash packageManager="bun"
 bun add intlayer @intlayer/sync-json-plugin --dev
-bun x intlayer init
 ```
 
 **Descrição dos pacotes:**
@@ -88,7 +102,9 @@ bun x intlayer init
 - **intlayer**: Biblioteca principal para gerenciamento de internacionalização, declaração de conteúdo e construção
 - **@intlayer/sync-json-plugin**: Plugin para exportar declarações de conteúdo do Intlayer para o formato JSON compatível com react-intl
 
-### Passo 2: Implemente o plugin Intlayer para encapsular o JSON
+</Step>
+
+<Step number={2} title="Implemente o plugin Intlayer para encapsular o JSON">
 
 Crie um arquivo de configuração do Intlayer para definir os seus locais suportados:
 
@@ -125,7 +141,9 @@ Se alterações forem feitas usando o CLI para traduzir o JSON, ou usando o CMS,
 
 Para ver mais detalhes sobre o plugin `syncJSON`, por favor consulte a [documentação do plugin syncJSON](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/plugins/sync-json.md).
 
-### (Opcional) Passo 3: Implementar traduções JSON por componente
+</Step>
+
+<Step number={3} title="Implementar traduções JSON por componente" isOptional={true}>
 
 Por padrão, o Intlayer irá carregar, mesclar e sincronizar tanto os arquivos JSON quanto os arquivos de declaração de conteúdo. Veja [a documentação da declaração de conteúdo](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/dictionary/content_file.md) para mais detalhes. Mas se preferir, usando um plugin do Intlayer, você também pode implementar o gerenciamento por componente de JSON localizado em qualquer lugar da sua base de código.
 
@@ -167,6 +185,10 @@ export default config;
 
 Isso carregará todos os arquivos JSON no diretório `src` que correspondem ao padrão `{key}.i18n.json` e os carregará como dicionários do Intlayer.
 
+</Step>
+
+</Steps>
+
 ## Configuração do Git
 
 É recomendado ignorar os arquivos gerados automaticamente pelo Intlayer:

package/blog/pt/intlayer_with_vue-i18n.md

@@ -57,28 +57,46 @@ Este guia mostra como aproveitar o sistema superior de declaração de conteúdo
 
 ## Guia Passo a Passo para Configurar o Intlayer com vue-i18n
 
-### Passo 1: Instalar Dependências
+<Steps>
+
+<Step number={1} title="Instalar Dependências">
 
 Instale os pacotes necessários usando seu gerenciador de pacotes preferido:
 
+```bash packageManager="npm"
+npx intlayer-cli init --interactive
+```
+
+```bash packageManager="pnpm"
+pnpm dlx intlayer-cli init --interactive
+```
+
+```bash packageManager="yarn"
+yarn dlx intlayer-cli init --interactive
+```
+
+```bash packageManager="bun"
+bunx intlayer-cli init --interactive
+```
+
+> a flag `--interactive` é opcional. Use `intlayer-cli init` se você for um agente de IA.
+
+> Este comando detectará seu ambiente e instalará os pacotes necessários. Por exemplo:
+
 ```bash packageManager="npm"
 npm install intlayer @intlayer/sync-json-plugin --save-dev
-npx intlayer init
 ```
 
 ```bash packageManager="pnpm"
 pnpm add intlayer @intlayer/sync-json-plugin --save-dev
-pnpm intlayer init
 ```
 
 ```bash packageManager="yarn"
 yarn add intlayer @intlayer/sync-json-plugin --dev
-yarn intlayer init
 ```
 
 ```bash packageManager="bun"
 bun add intlayer @intlayer/sync-json-plugin --dev
-bun x intlayer init
 ```
 
 **Explicações dos pacotes:**
@@ -86,7 +104,9 @@ bun x intlayer init
 - **intlayer**: Biblioteca principal para declaração e gerenciamento de conteúdo
 - **@intlayer/sync-json-plugin**: Plugin para sincronizar declarações de conteúdo do Intlayer para o formato JSON do vue-i18n
 
-### Passo 2: Implemente o plugin Intlayer para encapsular o JSON
+</Step>
+
+<Step number={2} title="Implemente o plugin Intlayer para encapsular o JSON">
 
 Crie um arquivo de configuração do Intlayer para definir os seus locais suportados:
 
@@ -125,7 +145,9 @@ Para ver mais detalhes sobre o plugin `syncJSON`, por favor consulte a [document
 
 ---
 
-### (Opcional) Passo 3: Implementar traduções JSON por componente
+</Step>
+
+<Step number={3} title="Implementar traduções JSON por componente" isOptional={true}>
 
 Por padrão, o Intlayer irá carregar, mesclar e sincronizar tanto os arquivos JSON quanto os arquivos de declaração de conteúdo. Veja [a documentação da declaração de conteúdo](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/dictionary/content_file.md) para mais detalhes. Mas se preferir, usando um plugin do Intlayer, você também pode implementar o gerenciamento por componente de JSON localizado em qualquer lugar da sua base de código.
 
@@ -169,6 +191,10 @@ Isso carregará todos os arquivos JSON no diretório `src` que correspondem ao p
 
 ---
 
+</Step>
+
+</Steps>
+
 ## Configuração do Git
 
 Exclua arquivos gerados do controle de versão:

package/blog/pt/l10n_platform_alternative/crowdin.md

@@ -24,12 +24,6 @@ author: aymericzip
 
 <TOC/>
 
-# Sistema de Gestão de Traduções
-
-Um Translation Management System (TMS) é uma plataforma de software projetada para automatizar e otimizar o processo de tradução e localização (L10n). Tradicionalmente, um TMS funciona como um hub centralizado onde o conteúdo é carregado, organizado e atribuído a tradutores humanos. Ele gere fluxos de trabalho, armazena memórias de tradução (para evitar retraduzir a mesma frase duas vezes) e trata da entrega dos ficheiros traduzidos de volta aos desenvolvedores ou gestores de conteúdo.
-
-Na prática, historicamente um TMS tem sido a ponte entre o código técnico (onde as strings residem) e os linguistas humanos (que compreendem a cultura).
-
 # Crowdin
 
 Um Sistema de Gestão de Tradução (TMS) é uma plataforma de software projetada para automatizar e agilizar o processo de tradução e localização (L10n). Tradicionalmente, um TMS funciona como um hub centralizado onde o conteúdo é carregado, organizado e atribuído a tradutores humanos. Ele gere fluxos de trabalho, armazena memórias de tradução (para evitar traduzir a mesma frase duas vezes) e trata da entrega dos ficheiros traduzidos de volta aos desenvolvedores ou gestores de conteúdo.

package/blog/pt/next-i18next_vs_next-intl_vs_intlayer.md

@@ -284,34 +284,6 @@ Aqui está um exemplo do impacto da otimização do tamanho do bundle usando `in
 
 ---
 
-## DX, ferramentas e manutenção
-
-<Columns>
-  <Column>
-
-**next-intl**
-
-- Comumente emparelhado com plataformas externas de localização e fluxos editoriais.
-
-  </Column>
-  <Column>
-
-**next-i18next**
-
-- Comumente emparelhado com plataformas externas de localização e fluxos editoriais.
-
-  </Column>
-  <Column>
-
-**intlayer**
-
-- Fornece um **Editor Visual gratuito** e um **CMS opcional** (compatível com Git ou externalizado), além de uma **extensão para VSCode** e **traduções assistidas por IA** usando suas próprias chaves de provedor.
-
-  </Column>
-</Columns>
-
-**Por que isso importa:** Reduz o custo operacional e encurta o ciclo entre desenvolvedores e autores de conteúdo.
-
 ## Integração com plataformas de localização (TMS)
 
 Grandes organizações frequentemente dependem de Sistemas de Gerenciamento de Tradução (TMS) como **Crowdin**, **Phrase**, **Lokalise**, **Localizely** ou **Localazy**.
@@ -1178,6 +1150,127 @@ export default robots;
 
 ---
 
+### Middleware para roteamento de locale
+
+<Tabs defaultTab="next-intl" group='techno'>
+  <Tab label="next-i18next" value="next-i18next">
+
+Adicione um middleware para lidar com detecção de locale e roteamento:
+
+```ts fileName="src/middleware.ts"
+import { NextResponse, type NextRequest } from "next/server";
+import { defaultLocale, locales } from "@/i18n.config";
+
+const PUBLIC_FILE = /\.[^/]+$/; // excluir arquivos com extensões
+
+export function middleware(request: NextRequest) {
+  const { pathname } = request.nextUrl;
+
+  if (
+    pathname.startsWith("/_next") ||
+    pathname.startsWith("/api") ||
+    pathname.startsWith("/static") ||
+    PUBLIC_FILE.test(pathname)
+  ) {
+    return;
+  }
+
+  const hasLocale = locales.some(
+    (l) => pathname === "/" + l || pathname.startsWith("/" + l + "/")
+  );
+  if (!hasLocale) {
+    const locale = defaultLocale;
+    const url = request.nextUrl.clone();
+    url.pathname = "/" + locale + (pathname === "/" ? "" : pathname);
+    return NextResponse.redirect(url);
+  }
+}
+
+export const config = {
+  matcher: [
+    // Corresponder todos os caminhos exceto os que começam com estes e arquivos com extensão
+    "/((?!api|_next|static|.*\\..*).*)",
+  ],
+};
+```
+
+  </Tab>
+  <Tab label="next-intl" value="next-intl">
+
+Adicione um middleware para lidar com detecção de locale e roteamento:
+
+```ts fileName="src/middleware.ts"
+import createMiddleware from "next-intl/middleware";
+import { locales, defaultLocale } from "@/i18n";
+
+export default createMiddleware({
+  locales: [...locales],
+  defaultLocale,
+  localeDetection: true,
+});
+
+export const config = {
+  // Pular API, Next internals e assets estáticos
+  matcher: ["/((?!api|_next|.*\\..*).*)"],
+};
+```
+
+  </Tab>
+  <Tab label="intlayer" value="intlayer">
+
+O Intlayer fornece manipulação de middleware integrada através da configuração do pacote `next-intlayer`.
+
+```ts fileName="src/middleware.ts"
+import { intlayerProxy } from "next-intlayer/proxy";
+
+export const middleware = intlayerProxy();
+
+// aplica este middleware apenas a arquivos no diretório app
+export const config = {
+  matcher: "/((?!api|_next|static|.*\\..*).*)",
+};
+```
+
+A configuração do middleware está centralizada no arquivo `intlayer.config.ts`.
+
+  </Tab>
+</Tabs>
+
+### Lista de verificação de configuração e boas práticas
+
+<Tabs defaultTab="next-intl" group='techno'>
+  <Tab label="next-i18next" value="next-i18next">
+
+- Certifique-se de que `lang` e `dir` estão definidos no `<html>` raiz em `src/app/[locale]/layout.tsx`.
+- Divida as traduções em namespaces (por exemplo `common.json`, `about.json`) em `src/locales/<locale>/`.
+- Carregue apenas os namespaces necessários em componentes cliente usando `useTranslation('<ns>')` e escopo de `I18nProvider` com os mesmos namespaces.
+- Mantenha as páginas estáticas sempre que possível: exporte `export const dynamic = 'force-static'` nas páginas; defina `dynamicParams = false` e implemente `generateStaticParams`.
+- Use componentes servidor síncronos aninhados sob limites de cliente passando strings pré-computadas ou a função `t` e a `locale`.
+- Para SEO, defina `alternates.languages` nos metadados, liste URLs localizadas em `sitemap.ts` e desabilite rotas localizadas duplicadas em `robots.ts`.
+- Prefira formatadores com reconhecimento de locale (por exemplo, `Intl.NumberFormat(locale)`) e memorize-os no cliente se estiver usando React < 19.
+
+  </Tab>
+  <Tab label="next-intl" value="next-intl">
+
+- **Defina `lang` e `dir` do html**: Em `src/app/[locale]/layout.tsx`, compute `dir` via `getLocaleDirection(locale)` e defina `<html lang={locale} dir={dir}>`.
+- **Divida mensagens por namespace**: Organize JSON por locale e namespace (por exemplo, `common.json`, `about.json`).
+- **Minimize o payload do cliente**: Nas páginas, envie apenas os namespaces necessários para `NextIntlClientProvider` (por exemplo, `pick(messages, ['common', 'about'])`).
+- **Prefira páginas estáticas**: Exporte `export const dynamic = 'force-static'` e gere parâmetros estáticos para todos os `locales`.
+- **Componentes servidor síncronos**: Mantenha componentes servidor síncronos passando strings pré-computadas (rótulos traduzidos, números formatados) em vez de chamadas assíncronas ou funções não-serializáveis.
+
+  </Tab>
+  <Tab label="intlayer" value="intlayer">
+
+- **Conteúdo modular**: Co-localize dicionários de conteúdo com componentes usando arquivos `.content.{ts|js|json}`.
+- **Segurança de tipo**: Aproveite a integração do TypeScript para validação de conteúdo em tempo de compilação.
+- **Otimização em tempo de compilação**: Use as ferramentas de compilação do Intlayer para tree-shaking automático e otimização de bundle.
+- **Ferramentas integradas**: Aproveite o suporte integrado de roteamento, auxiliares de SEO e editor visual.
+
+  </Tab>
+</Tabs>
+
+---
+
 ## E o vencedor é…
 
 Não é simples. Cada opção tem seus prós e contras. Aqui está como eu vejo: