@intlayer/docs 5.5.10 → 5.5.12

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

@@ -0,0 +1,285 @@
+---
+createdAt: 2024-08-11
+updatedAt: 2025-06-29
+title: next-i18next vs next-intl vs Intlayer
+description: Compare o next-i18next com o next-intl e Intlayer para a internacionalização (i18n) de um aplicativo Next.js
+keywords:
+  - next-intl
+  - next-i18next
+  - Intlayer
+  - Internacionalização
+  - Blogumentação
+  - Next.js
+  - JavaScript
+  - React
+slugs:
+  - blog
+  - next-i18next-vs-next-intl-vs-intlayer
+---
+
+# next-i18next VS next-intl VS Intlayer | Next.js Internacionalização (i18n)
+
+Abaixo está uma comparação concisa de **três bibliotecas populares** para internacionalização (i18n) de uma aplicação Next.js: **next-intl**, **next-i18next** e **Intlayer**.
+
+Este documento destaca os critérios principais:
+
+1. **Arquitetura** (mantendo as traduções próximas aos seus componentes)
+2. **Suporte a TypeScript**
+3. **Gerenciamento de traduções ausentes**
+4. **Suporte a Componentes de Servidor**
+5. **Roteamento e middleware aprimorados** para Next.js
+6. **Simplicidade de configuração**
+
+O guia também fornece uma **análise aprofundada do Intlayer**, mostrando por que pode ser uma escolha forte, especialmente para Next.js 13+, incluindo **App Router** e **Componentes de Servidor**.
+
+---
+
+## Visão Geral de Cada Biblioteca
+
+### 1. next-intl
+
+**Foco Principal**: Configuração rápida e fácil com uma abordagem leve para localização.
+
+- **Arquitetura**: Incentiva a co-localização de traduções em uma única pasta (por exemplo, `locales/`) mas também permite múltiplas estratégias. Não impõe estritamente uma arquitetura de “tradução por componente”.
+- **Suporte a TypeScript**: Integração básica com TypeScript. Algumas definições de tipo existem, mas não estão fortemente centradas na auto-geração de definições TypeScript a partir de seus arquivos de tradução.
+- **Traduções Ausentes**: Mecanismo de fallback básico. Por padrão, recai sobre uma chave ou uma string de locale padrão. Não há ferramentas robustas prontas para uso para checagens avançadas de traduções ausentes.
+- **Suporte a Componentes de Servidor**: Funciona com Next.js 13+ em geral, mas o padrão é menos especializado para uso profundo do lado do servidor (por exemplo, componentes de servidor com roteamento dinâmico complexo).
+- **Roteamento & Middleware**: O suporte a middleware é possível, mas limitado. Normalmente, depende do `Middleware` do Next.js para detecção de locale, ou configuração manual para reescrita de caminhos de locale.
+- **Simplicidade da Configuração**: Muito direto. Mínimo boilerplate é necessário.
+
+**Use quando**: Você deseja uma abordagem mais simples ou está confortável em gerenciar suas traduções de maneiras mais convencionais (como uma pasta com arquivos JSON de locale).
+
+---
+
+### 2. next-i18next
+
+**Foco Principal**: Solução testada pelo tempo usando `i18next` sob o capô, amplamente adotada para projetos Next.js.
+
+- **Arquitetura**: Geralmente organiza traduções na pasta `public/locales`. Não é especificamente projetado para manter traduções “próximas” a cada componente, embora você possa manualmente adotar uma estrutura diferente.
+- **Suporte a TypeScript**: Cobertura razoável de TypeScript, mas requer configuração personalizada para traduções tipadas e hooks tipados.
+- **Traduções Ausentes**: o i18next oferece interpolação/fallbacks. No entanto, a detecção de traduções ausentes geralmente precisa de configuração extra ou plugins de terceiros.
+- **Suporte a Componentes de Servidor**: O uso básico com Next.js 13 é documentado, mas o uso avançado (por exemplo, integração profunda com componentes de servidor, geração de rotas dinâmicas) pode ser complicado.
+- **Roteamento & Middleware**: Depende fortemente do `Middleware` do Next.js e reescritas para subcaminhos de locale. Para configurações mais complexas, você pode precisar mergulhar na configuração avançada do i18next.
+- **Simplicidade da Configuração**: Abordagem familiar para aqueles acostumados ao i18next. No entanto, pode ficar mais pesado em boilerplate quando recursos avançados de i18n são necessários (namespaces, múltiplos locales de fallback, etc.).
+
+**Use quando**: Você já está comprometido com o ecossistema `i18next` ou tem traduções existentes baseadas no i18next.
+
+---
+
+### 3. Intlayer
+
+**Foco Principal**: Uma biblioteca moderna e open-source de i18n especificamente adaptada para **App Router** do Next.js (12, 13, 14 e 15) com suporte embutido para **Componentes de Servidor** e **Turbopack**.
+
+#### Principais Vantagens
+
+1. **Arquitetura**
+
+   - Incentiva colocar **traduções bem ao lado de seus componentes**. Cada página ou componente pode ter seu próprio arquivo `.content.ts` (ou JSON), sem mais vasculhar uma pasta de tradução gigante.
+   - Isso torna seu código mais **modular e manutenível**, especialmente em grandes bases de código.
+
+2. **Suporte a TypeScript**
+
+   - **Definições de tipo auto-geradas**: No momento em que você define seu conteúdo, o Intlayer gera tipos que alimentam a conclusão automática e capturam erros de tradução.
+   - Minimiza erros em tempo de execução, como chaves ausentes e oferece **conclusão automática** avançada diretamente em seu IDE.
+
+3. **Gerenciamento de Traduções Ausentes**
+
+   - Durante a construção, o Intlayer pode **detectar chaves de tradução ausentes** e gerar avisos ou erros.
+   - Isso garante que você nunca envie acidentalmente traduções faltantes em seus idiomas.
+
+4. **Otimizado para Componentes de Servidor**
+
+   - Totalmente compatível com o **App Router** do Next.js e o novo paradigma de **Componentes de Servidor**.
+   - Fornece provedores especializados (`IntlayerServerProvider`, `IntlayerClientProvider`) para **isolar o contexto do servidor** (vital ao lidar com Next.js 13+).
+
+5. **Roteamento e Middleware Aprimorados**
+
+   - Inclui um [**`intlayerMiddleware`**](#) dedicado para **detecção automática de locale** (via cookies ou cabeçalhos do navegador) e geração avançada de rotas.
+   - Lida dinamicamente com caminhos localizados (por exemplo, `/en-US/about` vs. `/fr/about`) com configuração mínima.
+   - Oferece métodos auxiliares como `getMultilingualUrls` para gerar links de idiomas alternativos (ótimo para **SEO**).
+
+6. **Configuração Simplificada**
+   - Um único arquivo de configuração (`intlayer.config.ts`) para definir seus locales, locale padrão e preferências de integração.
+   - Um plugin wrapper `withIntlayer(nextConfig)` que **injeta** todas as variáveis de ambiente e observadores para seu conteúdo.
+   - **Sem grandes configurações de fallback**, o sistema foi feito para "simplesmente funcionar" com mínima fricção.
+
+> **Resumo**: O Intlayer é uma solução moderna que deseja **impulsionar as melhores práticas**: desde **manter traduções próximas** a cada componente React, até oferecer **suporte robusto a TS** e uso **fácil do lado do servidor**, enquanto **drasticamente reduz o boilerplate**.
+
+---
+
+## Comparação de Recursos Lado a Lado
+
+| **Recurso**                                | **next-intl**                                  | **next-i18next**                                | **Intlayer**                                    |
+| ------------------------------------------ | ---------------------------------------------- | ----------------------------------------------- | ----------------------------------------------- |
+| **Manter traduções perto dos componentes** | Parcial – tipicamente uma pasta de locales     | Não é padrão – frequentemente `public/locales`  | **Sim – recomendado e fácil**                   |
+| **TypeScript Autogerado**                  | Definições TS básicas                          | Suporte TS básico                               | **Sim – avançado e pronto para uso**            |
+| **Detecção de traduções ausentes**         | Principalmente strings fallback                | Principalmente strings fallback                 | **Sim – checagens em tempo de construção**      |
+| **Suporte a Componentes de Servidor**      | Funciona, mas não é especializado              | Suportado, mas pode ser verboso                 | **Total suporte com provedores especializados** |
+| **Roteamento & Middleware**                | Integrado manualmente com o middleware do Next | Fornecido via reescrita de configuração         | **Middleware i18n dedicado + hooks avançados**  |
+| **Complexidade da Configuração**           | Simples, configuração mínima                   | Tradicional, pode ser verboso para uso avançado | **Um arquivo de configuração e plugin**         |
+
+---
+
+## Por que Intlayer?
+
+Para equipes migrando ou construindo em cima do **Next.js App Router** (versões 13, 14 ou 15) com **Componentes de Servidor**, o Intlayer oferece:
+
+1. **Uma Arquitetura Simplificada**
+
+   - Cada rota ou componente contém suas próprias traduções. Isso promove clareza e manutenibilidade.
+
+2. **Integração Poderosa com TypeScript**
+
+   - Você ganha segurança a nível de compilador, evitando chaves de tradução "cheias de erros de digitação" ou ausentes.
+
+3. **Alertas Reais de Tradução Ausente**
+
+   - Se você esquecer uma chave ou tradução de idioma, será alertado em tempo de construção (em vez de enviar uma interface incompleta).
+
+4. **Roteamento Avançado Embutido**
+
+   - Detecção automática de locale, geração dinâmica de rotas e fácil gerenciamento de URLs localizadas estão incluídos.
+   - Um `intlayerMiddleware` padrão não requer reescritas profundas de configuração.
+
+5. **Configuração de Um Parada Só**
+
+   - Mínimo boilerplate: basta definir seu `intlayer.config.ts`, envelopar `next.config` com `withIntlayer`, e adicionar o middleware oficial.
+   - Uso claro e direto para ambos **componentes de servidor** e **cliente** via `IntlayerServerProvider` e `IntlayerClientProvider`.
+
+6. **Amigável para SEO**
+   - Helpers embutidos (`getMultilingualUrls`, atributos `hrefLang`, etc.) facilitam a produção de páginas e sitemaps compatíveis com SEO.
+
+---
+
+## Exemplo: Intlayer em Ação
+
+Abaixo está um _snippet muito_ condensado ilustrando como aproveitar o Intlayer em um projeto Next.js 15. Para os detalhes completos e exemplos de código, [confira o guia completo do Intlayer](#).
+
+<details>
+<summary>Exemplo passo a passo</summary>
+
+1. **Instalar & Configurar**
+
+   ```bash
+   npm install intlayer next-intlayer
+   ```
+
+   ```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;
+   ```
+
+2. **Usar o Plugin**
+
+   ```ts
+   // next.config.mjs
+   import { withIntlayer } from "next-intlayer/server";
+
+   /** @type {import('next').NextConfig} */
+   const nextConfig = {};
+
+   export default withIntlayer(nextConfig);
+   ```
+
+3. **Adicionar Middleware**
+
+   ```ts
+   // src/middleware.ts
+   export { intlayerMiddleware as middleware } from "next-intlayer/middleware";
+
+   export const config = {
+     matcher:
+       "/((?!api|static|assets|robots|sitemap|sw|service-worker|manifest|.*\\..*|_next).*)",
+   };
+   ```
+
+4. **Criar um Layout Localizado**
+
+   ```tsx
+   // src/app/[locale]/layout.tsx
+   import { getHTMLTextDir } from "intlayer";
+   import { NextLayoutIntlayer } from "next-intlayer";
+
+   const LocaleLayout: NextLayoutIntlayer = async ({ children, params }) => {
+     const { locale } = params;
+     return (
+       <html lang={locale} dir={getHTMLTextDir(locale)}>
+         <body>{children}</body>
+       </html>
+     );
+   };
+
+   export { generateStaticParams } from "next-intlayer";
+   export default LocaleLayout;
+   ```
+
+5. **Declarar & Usar Conteúdo**
+
+   ```tsx
+   // src/app/[locale]/page.content.ts
+   import { t } from "intlayer";
+
+   export default {
+     key: "page",
+     content: {
+       getStarted: {
+         main: t({
+           en: "Get started by editing",
+           fr: "Commencez par éditer",
+           es: "Comience por editar",
+         }),
+         pageLink: "src/app/page.tsx",
+       },
+     },
+   };
+   ```
+
+   ```tsx
+   // src/app/[locale]/page.tsx
+   import { IntlayerServerProvider } from "next-intlayer/server";
+   import { IntlayerClientProvider, useIntlayer } from "next-intlayer";
+
+   const PageContent = () => {
+     const { content } = useIntlayer("page");
+     return (
+       <>
+         <p>{content.getStarted.main}</p>
+         <code>{content.getStarted.pageLink}</code>
+       </>
+     );
+   };
+
+   export default function Page({ params }) {
+     return (
+       <IntlayerServerProvider locale={params.locale}>
+         <IntlayerClientProvider locale={params.locale}>
+           <PageContent />
+         </IntlayerClientProvider>
+       </IntlayerServerProvider>
+     );
+   }
+   ```
+
+   </details>
+
+---
+
+## Conclusão
+
+Cada solução, **next-intl**, **next-i18next** e **Intlayer**, tem se mostrado eficaz para projetos multilíngues Next.js. No entanto, **Intlayer** vai mais longe:
+
+- **Incentivando fortemente uma arquitetura de tradução a nível de componente**
+- Integrando-se perfeitamente com **Next.js 13+ e Componentes de Servidor**
+- Oferecendo **poderosa auto-geração de TypeScript** para código mais seguro
+- Lidando com **traduções ausentes** em tempo de construção
+- Fornecendo uma abordagem **simplificada e de configuração única** com roteamento e middleware avançados
+
+Se você deseja recursos de i18n **modernos** adaptados ao App Router do Next.js e procura uma experiência **totalmente tipada** sem precisar manualmente de lógica de fallback, reescritas de rotas ou etapas de construção complexas, **Intlayer** é uma escolha atraente. Ele não apenas reduz seu tempo de configuração, mas também garante uma abordagem mais manutenível e escalável para traduções para sua equipe.

package/blog/pt/react-i18next_vs_react-intl_vs_intlayer.md

@@ -0,0 +1,194 @@
+---
+createdAt: 2025-01-02
+updatedAt: 2025-06-29
+title: react-i18n vs react-intl vs Intlayer
+description: Integre o react-i18next com o next-intl e Intlayer para a internacionalização (i18n) de um aplicativo React
+keywords:
+  - next-intl
+  - react-i18next
+  - Intlayer
+  - Internacionalização
+  - Blogumentação
+  - Next.js
+  - JavaScript
+  - React
+slugs:
+  - blog
+  - react-i18next-vs-react-intl-vs-intlayer
+---
+
+# React-Intl VS React-i18next VS Intlayer | React Internationalization (i18n)
+
+Abaixo está uma comparação concisa de três bibliotecas populares de i18n (internacionalização) para React: **React-Intl**, **React-i18next** e **Intlayer**. Cada biblioteca oferece recursos e fluxos de trabalho exclusivos para integrar suporte multilíngue em sua aplicação React. Após ler isso, você deve ser capaz de decidir qual solução atende melhor às suas necessidades.
+
+---
+
+## 1. Introdução
+
+A internacionalização (i18n) em aplicações React pode ser alcançada de várias maneiras. As três bibliotecas apresentadas aqui têm diferentes filosofias de design, conjuntos de recursos e suporte da comunidade:
+
+1. **React-Intl**
+2. **React-i18next**
+3. **Intlayer**
+
+Abaixo, você encontrará uma visão geral de cada solução, seguida de uma comparação de recursos, prós e contras, e exemplos de casos de uso.
+
+---
+
+## 2. React-Intl
+
+### Visão Geral
+
+[**React-Intl**](https://formatjs.io/docs/react-intl/) é parte da [FormatJS](https://formatjs.io/) suite. Ele fornece um conjunto poderoso de **APIs e componentes** para lidar com formatação de mensagens, pluralização, data/hora e formatação de números. O React-Intl é amplamente utilizado em aplicações corporativas, principalmente porque faz parte de um ecossistema que padroniza a sintaxe e a formatação das mensagens.
+
+### Principais Recursos
+
+- **Sintaxe de Mensagem ICU**: Oferece uma sintaxe abrangente para interpolação de mensagens, pluralização e muito mais.
+- **Formatação Localizada**: Utilitários embutidos para formatar datas, horas, números e tempos relativos com base na localidade.
+- **Componentes Declarativos**: Expõe `<FormattedMessage>`, `<FormattedNumber>`, `<FormattedDate>`, etc., para uso sem costura em JSX.
+- **Ecossistema Rico**: Integra-se bem com as ferramentas FormatJS (por exemplo, [babel-plugin-react-intl](https://formatjs.io/docs/tooling/babel-plugin/) para extrair, gerenciar e compilar mensagens.
+
+### Fluxo de Trabalho Típico
+
+1. **Defina catálogos de mensagens** (geralmente arquivos JSON por localidade).
+2. **Envolva seu aplicativo** em `<IntlProvider locale="pt" messages={messages}>`.
+3. **Use** `<FormattedMessage id="myMessage" defaultMessage="Hello world" />` ou o hook `useIntl()` para acessar strings de tradução.
+
+### Prós
+
+- Bem estabelecido e usado em muitos ambientes de produção.
+- Formatação avançada de mensagens, incluindo pluralização, gênero, fusos horários e mais.
+- Forte suporte de ferramentas para extração e compilação de mensagens.
+
+### Contras
+
+- Requer familiaridade com o **formato de mensagem ICU**, que pode ser verboso.
+- Não é tão simples lidar com traduções dinâmicas ou complexas que são mais do que apenas baseadas em strings.
+
+---
+
+## 3. React-i18next
+
+### Visão Geral
+
+[**React-i18next**](https://react.i18next.com/) é uma extensão React de [i18next](https://www.i18next.com/), um dos frameworks de i18n JavaScript mais populares. Ele oferece **recursos extensos** para traduções em tempo de execução, carregamento preguiçoso e detecção de idioma, tornando-o extremamente flexível para uma ampla variedade de casos de uso.
+
+### Principais Recursos
+
+- **Estrutura de Tradução Flexível**: Não está atada a um único formato como ICU. Você pode armazenar traduções em JSON, usar interpolação, pluralização, etc.
+- **Alternância de Idioma Dinâmica**: Plugins de detector de idioma incorporados e atualizações em tempo de execução.
+- **Traduções Aninhadas e Estruturadas**: Você pode aninhar traduções facilmente dentro de JSON.
+- **Ecossistema de Plugins Extensivo**: Para detecção (navegador, caminho, subdomínio, etc.), carregamento de recursos, cache e mais.
+
+### Fluxo de Trabalho Típico
+
+1. **Instale `i18next` e `react-i18next`.**
+2. **Configure i18n** para carregar traduções (JSON) e configurar detecção de idioma ou fallback.
+3. **Envolva seu aplicativo** em `I18nextProvider`.
+4. **Use o hook `useTranslation()`** ou o componente `<Trans>` para exibir traduções.
+
+### Prós
+
+- **Altamente flexível** e rico em recursos.
+- Comunidade muito ativa e grande ecossistema de plugins.
+- Facilidade de **carregamento dinâmico** de traduções (por exemplo, de um servidor, sob demanda).
+
+### Contras
+
+- **A configuração pode ser verbosa**, especialmente se você tiver necessidades mais avançadas.
+- Se você prefere traduções fortemente tipadas, pode precisar de configurações adicionais do TypeScript.
+
+---
+
+## 4. Intlayer
+
+### Visão Geral
+
+[**Intlayer**](https://github.com/aymericzip/intlayer) é uma biblioteca de i18n open-source mais nova, focada em **declarações de conteúdo em nível de componente**, segurança de tipo e **roteamento dinâmico**. É projetada para fluxos de trabalho modernos do React, suportando tanto **Create React App** quanto configurações de **Vite**. Também inclui recursos avançados como **roteamento baseado em localidade** e **tipos TypeScript gerados automaticamente** para traduções.
+
+### Principais Recursos
+
+- **Arquivos de Conteúdo Declarativos**: Cada componente ou módulo pode declarar suas traduções em arquivos dedicados `.content.tsx` ou `.content.json`, mantendo o conteúdo próximo de onde é usado.
+- **Roteamento & Middleware Incorporados**: Módulos opcionais para roteamento localizado (por exemplo, `/pt/sobre`, `/fr/about`) e middleware do servidor para detectar a localidade do usuário.
+- **Tipos TypeScript Gerados Automaticamente**: Garante segurança de tipo com recursos como autocompletar e detecção de erros em tempo de compilação.
+- **Traduções Dinâmicas e Ricas**: Podem incluir JSX/TSX em traduções para casos de uso mais complexos (por exemplo, links, texto em negrito, ícones em traduções).
+
+### Fluxo de Trabalho Típico
+
+1. **Instale `intlayer` e `react-intlayer`.**
+2. **Crie `intlayer.config.ts`** para definir localidades disponíveis e a localidade padrão.
+3. **Use a CLI do Intlayer** ou o plugin para **transpilar** declarações de conteúdo.
+4. **Envolva seu aplicativo** em `<IntlayerProvider>` e recupere o conteúdo com `useIntlayer("keyName")`.
+
+### Prós
+
+- **Amigável ao TypeScript** com geração de tipos integrada e verificação de erros.
+- **Conteúdo rico** possível (por exemplo, passando nós React como traduções).
+- **Roteamento Localizado** pronto para uso.
+- Integrado com ferramentas de build populares (CRA, Vite) para configuração fácil.
+
+### Contras
+
+- Ainda **relativamente novo** em comparação com React-Intl ou React-i18next.
+- Foco maior em uma abordagem de “declaração de conteúdo em nível de componente”, pode ser uma mudança em relação aos catálogos típicos em .json.
+- Ecossistema e comunidade menores em comparação com as bibliotecas mais estabelecidas.
+
+---
+
+## 5. Comparação de Recursos
+
+| **Recurso**                   | **React-Intl**                                                                   | **React-i18next**                                                                                                    | **Intlayer**                                                                                                                                |
+| ----------------------------- | -------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Caso de Uso Principal**     | Traduções baseadas em string, formatação de data/número, sintaxe de mensagem ICU | i18n completo com fácil troca dinâmica, aninhamento, ecossistema de plugins                                          | Traduções seguras em tipos com foco em conteúdo declarativo, roteamento localizado e middleware opcional de servidor                        |
+| ** abordagem **               | Utilize `<IntlProvider>` & componentes de mensagem FormatJS                      | Utilize `I18nextProvider` & hook `useTranslation()`                                                                  | Utilize `<IntlayerProvider>` & hook `useIntlayer()` com declarações de conteúdo                                                             |
+| **Formato de Localização**    | Strings baseadas em ICU (catálogos JSON ou JavaScript)                           | Arquivos de recurso JSON (ou carregadores personalizados). Formato ICU opcional via plugin i18next                   | Declarações em `.content.[ts/js/tsx]` ou JSON; podem conter strings ou componentes React                                                    |
+| **Roteamento**                | Tratado externamente (sem roteamento localizado embutido)                        | Tratado externamente com plugins i18next (detecção de caminho, subdomínio, etc.)                                     | Suporte embutido para roteamento localizado (por exemplo, `/pt/sobre`, `/fr/about`), além de middleware opcional (para SSR/Vite)            |
+| **Suporte ao TypeScript**     | Bom (tipagens para pacotes oficiais)                                             | Bom, mas configuração extra para traduções tipadas se você quiser verificação rigorosa                               | Excelente (definições de tipo geradas automaticamente para chaves de conteúdo e traduções)                                                  |
+| **Pluralização & Formatação** | Avançado: formatação de data/hora/número incorporada, suporte a plural/gênero    | Pluralização configurável. A formatação de data/hora é normalmente feita por meio de libs externas ou plugin i18next | Pode depender de JavaScript Intl padrão ou embutir lógica no conteúdo. Não tão especializado quanto o FormatJS, mas lida com casos típicos. |
+| **Comunidade & Ecossistema**  | Grande, parte do ecossistema FormatJS                                            | Muito grande, altamente ativo, muitos plugins (detecção, caching, frameworks)                                        | Menor, mas crescente; abordagem moderna, open-source                                                                                        |
+| **Curva de Aprendizado**      | Moderada (aprendendo a sintaxe de mensagem ICU, convenções do FormatJS)          | Baixa a moderada (uso direto, mas configuração avançada pode se tornar verbosa)                                      | Moderada (conceito de declarações de conteúdo e etapas de build especializadas)                                                             |
+
+---
+
+## 6. Quando Escolher Cada Um
+
+1. **React-Intl**
+
+   - Você precisa de **formatação poderosa** para datas/horas/números e de forte **sintaxe de mensagem ICU**.
+   - Você prefere uma abordagem mais “**baseada em padrões**” para traduções.
+   - Você não requer roteamento localizado ou chaves de tradução fortemente tipadas.
+
+2. **React-i18next**
+
+   - Você precisa de uma solução **flexível, estabelecida** com carregamento **dinâmico** e **sob demanda** de traduções.
+   - Você deseja detecção de idioma **baseada em plugins** (por exemplo, a partir de URL, cookies, armazenamento local) ou cache avançado.
+   - Você precisa do maior ecossistema, com muitas integrações existentes para vários frameworks (Next.js, React Native, etc.).
+
+3. **Intlayer**
+   - Você deseja uma forte integração com TypeScript com _tipos gerados automaticamente_, garantindo que você raramente perca uma chave de tradução.
+   - Você prefere **conteúdo declarativo** próximo do componente, possivelmente incluindo nós React ou lógica avançada em traduções.
+   - Você requer **roteamento localizado embutido** ou deseja facilmente incorporá-lo em sua configuração de SSR ou Vite.
+   - Você deseja uma abordagem moderna ou simplesmente quer uma única biblioteca que cubra tanto a **gestão de conteúdo** (i18n) quanto o **roteamento** de forma segura.
+
+---
+
+## 7. Conclusão
+
+Cada biblioteca oferece uma solução robusta para internacionalizar uma aplicação React:
+
+- **React-Intl** é excelente em formatação de mensagens e é uma escolha popular para soluções empresariais focadas na sintaxe de mensagem ICU.
+- **React-i18next** fornece um ambiente altamente flexível, impulsionado por plugins para necessidades avançadas ou dinâmicas de i18n.
+- **Intlayer** oferece uma abordagem **moderna e fortemente tipada** que une declarações de conteúdo, roteamento localizado avançado e integrações baseadas em plugins (CRA, Vite).
+
+Sua escolha depende em grande parte dos requisitos do projeto, da experiência desejada do desenvolvedor (DX) e da importância de traduções tipadas ou roteamento avançado. Se você valoriza o roteamento localizado embutido e a integração com TypeScript, **Intlayer** pode ser a mais atraente. Se você deseja uma solução robusta e rica em ecossistemas, **React-i18next** é uma ótima escolha. Para necessidades de formatação baseadas em ICU mais diretas, **React-Intl** é uma opção confiável.
+
+---
+
+### Leitura Adicional
+
+- [Documentação do React-Intl](https://formatjs.io/docs/react-intl/)
+- [Documentação do React-i18next](https://react.i18next.com/)
+- [Intlayer + Guia de Introdução ao CRA](#) (do seu doc)
+- [Intlayer + Guia de Introdução ao Vite & React](#) (do seu doc)
+
+Sinta-se à vontade para misturar e combinar abordagens para atender às suas necessidades, não há uma “solução única para todos”, e cada biblioteca continua a evoluir para abordar novos casos de uso no ecossistema React.

package/blog/pt/what_is_internationalization.md

@@ -0,0 +1,165 @@
+---
+createdAt: 2025-01-16
+updatedAt: 2025-06-29
+title: O que é internacionalização (i18n)? Definição e desafios
+description: Descubra por que internacionalizar seu site é essencial. Aprenda os princípios-chave para acelerar o SEO, melhorar a experiência do usuário e expandir a sua alcance global.
+keywords:
+  - i18n
+  - multilíngue
+  - SEO
+  - Internacionalização
+  - Blog
+  - Next.js
+  - JavaScript
+  - React
+slugs:
+  - blog
+  - what-is-internationalization
+---
+
+# O que é Internacionalização (i18n)? Definição e desafios
+
+![ilustração de i18n](https://github.com/aymericzip/intlayer/blob/main/docs/assets/i18n.webp)
+
+## Entendendo a Internacionalização (i18n)
+
+**Internacionalização**, frequentemente abreviada como **i18n**, é o processo de projetar e preparar uma aplicação para suportar múltiplos idiomas, culturas e convenções regionais **sem** mudanças maiores na base de código. O nome i18n é derivado do fato de que há 18 letras entre o **i** e o **n** na palavra “internacionalização”.
+
+## Por que a i18n é Importante
+
+### SEO
+
+A internacionalização desempenha um papel crítico em melhorar a Otimização para Mecanismos de Busca (SEO) de um site. Mecanismos de busca como Google e Bing analisam a linguagem e a relevância cultural do seu conteúdo para determinar sua classificação. Ao adaptar seu site para suportar múltiplos idiomas e formatos regionais, você pode melhorar significativamente sua visibilidade nos resultados de busca. Isso não apenas atrai um público mais amplo, mas também ajuda seu site a classificar mais alto, uma vez que os mecanismos de busca reconhecem o esforço investido em atender a uma base de usuários diversificada.
+
+### Alcance Global
+
+Igualmente importante é o alcance global que a internacionalização oferece. Ao remover barreiras linguísticas e projetar sua aplicação para suportar várias normas culturais, você abre as portas para milhões de potenciais usuários de todo o mundo. Fornecer conteúdo e interfaces de usuário localizadas diferencia seu produto de concorrentes que podem oferecer suporte apenas para um número limitado de idiomas. Essa abordagem inclusiva garante que os usuários se sintam reconhecidos e valorizados, não importa onde estejam, ampliando assim o mercado do seu produto e aumentando sua competitividade em um cenário global.
+
+### Experiência do Usuário
+
+Outro benefício significativo da i18n é a melhoria na experiência do usuário. Os usuários tendem a se sentir mais confortáveis e conectados a softwares que se comunicam em sua língua nativa e respeitam convenções locais como formatos de data, moedas e unidades de medida. Essa experiência personalizada é fundamental para construir confiança e satisfação, promovendo a retenção de usuários a longo prazo. Quando os usuários podem navegar e entender uma aplicação sem dificuldades, eles têm mais probabilidade de se engajar profundamente com ela, abrindo caminho para avaliações positivas, referências e crescimento sustentado.
+
+## Internacionalização (i18n) vs. Localização (l10n)
+
+**Internacionalização (i18n)** é o processo de projetar seu produto de modo que ele possa facilmente suportar múltiplos idiomas e diferenças regionais. Por exemplo, se você construir um site com a internacionalização em mente, garantirá que os campos de texto suportem vários conjuntos de caracteres, as datas sigam diferentes formatos locais e os layouts se ajustem para expansão de texto ao traduzir para outros idiomas.
+
+**Localização (l10n)** é o trabalho realizado após a internacionalização. Envolve traduzir o conteúdo e adaptar os detalhes culturais para atender às necessidades de um público específico. Por exemplo, uma vez que um site foi internacionalizado, você pode localizá-lo para usuários franceses traduzindo todo o texto, alterando o formato de data para dia/mês/ano e até ajustando imagens ou ícones para melhor se adequar às normas culturais francesas.
+
+Em resumo, a internacionalização prepara seu produto para uso global, enquanto a localização o adapta para um mercado específico.
+
+## O que deve ser internacionalizado em um site?
+
+1. **Conteúdo de Texto:** Todos os elementos escritos como títulos, texto do corpo e botões precisam de tradução. Por exemplo, um título como "Welcome to our website" deve ser transformado em "Bem-vindo ao nosso site" para audiências em português.
+
+2. **Mensagens de Erro:** Notificações de erro claras e concisas são essenciais. Se um erro de formulário diz "Invalid email address", ele deve ser traduzido para o português como "Endereço de e-mail inválido" para ajudar os usuários a compreenderem o problema.
+
+3. **E-mails e Notificações:** Comunicações automatizadas, incluindo redefinições de senha ou confirmações de pedidos, devem ser localizadas. Um e-mail de confirmação de pedido pode cumprimentar um usuário com "Dear Customer" em inglês e "Caro Cliente" em português para a audiência apropriada.
+
+4. **Labels de Acessibilidade:** Rótulos e texto alternativo para imagens precisam ser traduzidos para que as tecnologias assistivas funcionem corretamente. Uma imagem com o texto alternativo "Smiling child playing" deve ser adaptada para "Criança sorridente brincando" em português.
+
+5. **Numeração:** Diferentes regiões formatam números de maneiras diferentes. Enquanto **“1.000,50”** funciona para localidades de língua portuguesa, muitos formatos europeus requerem **“1.000,50,”** tornando a adaptação local importante.
+
+6. **Moeda:** Exibir preços usando símbolos e formatos corretos para o local. Por exemplo, um item com preços de **“R$99,99”** no Brasil deve ser convertido para **“€97,10”** ao direcionar clientes europeus.
+
+7. **Unidades de Medida:** Unidades como temperatura, distância e volume devem ser exibidas de acordo com as preferências locais. Por exemplo, um aplicativo de clima pode mostrar **“20°C”** para usuários na Europa, mas **“68°F”** para outros.
+
+8. **Direção do Texto:** A ordem de leitura e o layout devem ser ajustados para idiomas com direções diferentes. Um site em inglês (da esquerda para a direita) deve alterar seu alinhamento ao ser localizado para árabe, que é lido da direita para a esquerda.
+
+9. **Data e Hora:** Os formatos variam entre regiões. Um evento exibido como **“12/25/2025 at 3:00 PM”** nos EUA pode precisar ser mostrado como **“25/12/2025 às 15:00”** em outros lugares para evitar confusão.
+
+10. **Fuso Horário**: Ajustar para os fusos horários locais garante que conteúdos sensíveis ao tempo como **horários de eventos, horários de entrega ou horas de atendimento ao cliente** sejam apresentados de forma precisa. Por exemplo, um webinar online agendado para **"3:00 PM EST"** deve ser convertido para o horário local correspondente, como **"8:00 PM GMT"** para usuários no Reino Unido.
+
+Este resumo conciso cobre os principais elementos que devem ser internacionalizados, garantindo que o conteúdo seja acessível, culturalmente apropriado e facilmente compreensível por uma audiência global.
+
+## Desafios Comuns da i18n
+
+![ilustração de dor da i18n](https://github.com/aymericzip/intlayer/blob/main/docs/assets/pain_i18n.webp)
+
+- **manutenibilidade**  
+  Cada atualização de site deve ser espelhada em todos os idiomas, exigindo fluxos de trabalho eficientes e cuidadosa coordenação para garantir consistência em todas as versões.
+
+- **Concatenação de Strings**  
+  Evite construir mensagens como `"Hello, " + username + "!"` uma vez que a ordem das palavras pode diferir por idioma; em vez disso, use marcadores como `Hello, {username}!` para acomodar variações linguísticas.
+
+- **Pluralização**  
+  Diferentes idiomas têm regras plurais variadas, às vezes com múltiplas formas. Utilizar bibliotecas como ICU MessageFormat pode simplificar o tratamento dessas complexidades de pluralização.
+
+- **Comprimento de UI e texto**  
+  Alguns idiomas, alemão, por exemplo, tendem a ter textos mais longos do que o inglês. Isso pode interromper layouts se o design não for flexível, então um design responsivo é fundamental.
+
+- **Codificação de caracteres**  
+  Usar a codificação de caracteres adequada (como UTF-8) é crucial para exibir corretamente diversos alfabetos e símbolos, prevenindo textos mal interpretados ou distorcidos.
+
+- **Layouts hardcoded**  
+  Componentes UI de tamanho fixo podem não se ajustar bem a traduções mais longas, levando a transbordamento de texto. Um layout flexível e responsivo ajuda a mitigar esse problema.
+
+- **Mudança dinâmica de linguagem**  
+  Os usuários esperam mudar de idioma sem reiniciar a aplicação ou reautenticar-se. Esse recurso requer uma implementação suave e bem planejada na arquitetura.
+
+- **Suporte à direção da língua**  
+  Ignorar o suporte para idiomas da direita para a esquerda (RTL) pode criar desafios significativos de redesign mais tarde. É melhor planejar a compatibilidade com RTL desde o início.
+
+- **Sensibilidades culturais**  
+  Ícones, cores e símbolos podem carregar significados diferentes entre culturas. É importante adaptar conteúdo visual e textual para respeitar as nuances culturais locais.
+
+---
+
+## Melhores Práticas para Implementar i18n
+
+- **Planeje cedo**  
+  Integre a internacionalização desde o início do seu projeto. Abordar a i18n logo no início é menos custoso e mais simples do que retrofitar mais tarde, garantindo um processo de desenvolvimento mais suave desde o começo.
+
+- **Automatize o gerenciamento de traduções**  
+  Utilize serviços de tradução baseados em IA, como os fornecidos pela Intlayer, para gerenciar suas traduções de forma eficiente. Com a automação, quando você publica um novo artigo, todas as traduções são construídas automaticamente, economizando tempo e reduzindo erros manuais.
+
+- **Usando Editor Visual**  
+  Implemente um editor visual para ajudar tradutores a ver o conteúdo em seu contexto real de UI. Ferramentas como o editor visual da Intlayer minimizam erros e confusões, garantindo que as traduções sejam precisas e reflitam o design final.
+
+- **Reutilização de Traduções**  
+  Organize seus arquivos de tradução para serem reutilizáveis em vários sites ou aplicações. Por exemplo, se você tem um rodapé ou cabeçalho multilíngue, configure arquivos de tradução dedicados para que elementos comuns possam ser facilmente aplicados a todos os projetos.
+
+---
+
+## Declaração de Conteúdo Localizado vs. Externalização de Conteúdo CMS
+
+Ao criar um site, um **Sistema de Gerenciamento de Conteúdo (CMS) como WordPress, Wix ou Drupal geralmente oferece melhor manutenibilidade**. Especialmente para blogs ou páginas de destino, por causa de suas funcionalidades integradas de i18n.
+
+No entanto, para aplicações com recursos complexos ou lógica de negócios, um **CMS pode se mostrar muito inflexível, e você pode precisar considerar uma biblioteca de i18n**.
+
+**O desafio com muitas bibliotecas de i18n é que frequentemente requerem que as traduções sejam hardcoded na base de código**. Isso significa que, se um gerente de conteúdo quiser atualizar uma tradução, ele é forçado a modificar o código e reconstruir a aplicação. Para aliviar esse problema, algumas ferramentas emergiram como "CMS baseados em Git" ou "CMS de i18n" para auxiliar gerentes de conteúdo. No entanto, mesmo **essas soluções normalmente exigem uma atualização da base de código e uma reconstrução quando alterações de conteúdo são feitas**.
+
+Diante desses desafios, é comum optar por um CMS headless para externalizar o conteúdo e simplificar o gerenciamento de traduções. No entanto, existem desvantagens notáveis ao usar um CMS para internacionalização:
+
+- **Nem todos os CMS oferecem recursos de i18n:** Algumas plataformas de CMS populares carecem de robustas capacidades de internacionalização, forçando você a procurar plugins adicionais ou soluções alternativas.
+- **Configuração duplicada:** Gerenciar traduções muitas vezes envolve configurar tanto o CMS quanto o código da aplicação, levando a uma duplicação de esforços e potenciais inconsistências.
+- **Difícil de manter:** Com traduções espalhadas entre o CMS e o código, manter um sistema consistente e livre de erros pode tornar-se desafiador ao longo do tempo.
+- **Custo de licenças:** Plataformas de CMS premium ou ferramentas de i18n adicionais podem introduzir custos de licenciamento extras que podem não ser viáveis para cada projeto.
+
+É importante escolher a ferramenta certa para suas necessidades e planejar sua estratégia de internacionalização desde o início. **A Intlayer oferece uma solução atraente combinando declaração de conteúdo localizado com um CMS headless que é intimamente integrado, proporcionando o melhor de ambos os mundos.**
+
+---
+
+### Veja a lista de bibliotecas e ferramentas de i18n por tecnologia
+
+Se você está procurando uma lista de bibliotecas e ferramentas de i18n por tecnologia, confira os seguintes recursos:
+
+### Para Sistemas de Gerenciamento de Conteúdo (CMS)
+
+- WordPress: [Veja a lista de bibliotecas e ferramentas de i18n](https://github.com/aymericzip/intlayer/blob/main/docs/blog/pt/list_i18n_technologies/CMS/wordpress.md)
+- Drupal: [Veja a lista de bibliotecas e ferramentas de i18n](https://github.com/aymericzip/intlayer/blob/main/docs/blog/pt/list_i18n_technologies/CMS/drupal.md)
+
+### Para Aplicações JavaScript (Frontend)
+
+- React: [Veja a lista de bibliotecas e ferramentas de i18n](https://github.com/aymericzip/intlayer/blob/main/docs/blog/pt/list_i18n_technologies/frameworks/react.md)
+- Angular: [Veja a lista de bibliotecas e ferramentas de i18n](https://github.com/aymericzip/intlayer/blob/main/docs/blog/pt/list_i18n_technologies/frameworks/angular.md)
+- Vue: [Veja a lista de bibliotecas e ferramentas de i18n](https://github.com/aymericzip/intlayer/blob/main/docs/blog/pt/list_i18n_technologies/frameworks/vue.md)
+- Svelte: [Veja a lista de bibliotecas e ferramentas de i18n](https://github.com/aymericzip/intlayer/blob/main/docs/blog/pt/list_i18n_technologies/frameworks/svelte.md)
+- React Native: [Veja a lista de bibliotecas e ferramentas de i18n](https://github.com/aymericzip/intlayer/blob/main/docs/blog/pt/list_i18n_technologies/frameworks/react-native.md)
+
+---
+
+## Conclusão
+
+A internacionalização (i18n) é mais do que apenas uma tarefa técnica; é um **investimento estratégico** que permite que seu software fale a língua dos seus usuários, literalmente. Ao abstrair elementos específicos do local, acomodar variações linguísticas e culturais e planejar para a expansão futura, você capacita seu produto a prosperar em um mercado global.
+
+Seja você construindo um aplicativo móvel, uma plataforma SaaS ou uma ferramenta empresarial, **a i18n garante que seu produto possa se adaptar e atrair usuários de todo o mundo**, sem a necessidade de reescritas constantes de código. Ao aproveitar melhores práticas, estruturas robustas e estratégias contínuas de localização, desenvolvedores e equipes de produtos podem oferecer experiências de software **verdadeiramente globais**.