Traduza seu Create React App com Intlayer | Internacionalização (i18n)

Consulte Application Template no GitHub.

O que é Intlayer?

Em comparação com soluções principais como react-i18next ou i18next, Intlayer é uma solução que vem com otimizações integradas, tais como:

Guia Passo a Passo para Configurar o Intlayer em uma Aplicação React

1. 1

   Instalar Dependências

   Instale os pacotes necessários usando npm:

   bash

   Copiar conteúdo

   Copiar código

   Copiar o código para a área de transferência

   npx intlayer 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

   Copiar conteúdo

   Copiar código

   Copiar o código para a área de transferência

   npm install intlayer react-intlayer react-scripts-intlayer
   

   • intlayer

     O pacote principal que fornece ferramentas de internacionalização para gerenciamento de configuração, tradução, declaração de conteúdo, transpilação e comandos CLI.

   • react-intlayer

     O pacote que integra o Intlayer com a aplicação React. Ele fornece provedores de contexto e hooks para internacionalização no React.

   • react-scripts-intlayer

   Inclui os comandos e plugins react-scripts-intlayer para integrar o Intlayer com a aplicação baseada no Create React App. Esses plugins são baseados no craco e incluem configuração adicional para o empacotador Webpack.

2. 2

   Configuração do seu projeto

   Crie um arquivo de configuração para configurar os idiomas da sua aplicação:

   intlayer.config.ts

   Copiar conteúdo

   Copiar código

   Copiar o código para a área de transferência

   import { Locales, type IntlayerConfig } from "intlayer";
   
   const config: IntlayerConfig = {
     internationalization: {
       locales: [
         Locales.ENGLISH,
         Locales.FRENCH,
         Locales.SPANISH,
         // Seus outros idiomas
       ],
       defaultLocale: Locales.ENGLISH,
     },
   };
   
   export default config;
   

   Por meio deste arquivo de configuração, você pode configurar URLs localizadas, redirecionamento de middleware, nomes de cookies, a localização e extensão de suas declarações de conteúdo, desativar logs do Intlayer no console e muito mais. Para uma lista completa de parâmetros disponíveis, consulte a documentação de configuração.

3. 3

   Integrar o Intlayer na Configuração do CRA

   Altere seus scripts para usar o react-intlayer

   package.json

   Copiar conteúdo

   Copiar código

   Copiar o código para a área de transferência

     "scripts": {
       "build": "react-scripts-intlayer build",
       "start": "react-scripts-intlayer start",
       "transpile": "intlayer build"
     },
   

   Os scripts react-scripts-intlayer são baseados no CRACO. Você também pode implementar sua própria configuração baseada no plugin craco do intlayer. Veja o exemplo aqui.

4. 4

   Declarar Seu Conteúdo

   Crie e gerencie suas declarações de conteúdo para armazenar traduções:

   src/app.content.tsx

   Copiar conteúdo

   Copiar código

   Copiar o código para a área de transferência

   import { t, type Dictionary } from "intlayer";
   import React, { type ReactNode } from "react";
   
   const appContent = {
     key: "app",
     content: {
       getStarted: t<ReactNode>({
         en: (
           <>
             Edit <code>src/App.tsx</code> and save to reload
           </>
         ),
         fr: (
           <>
             Éditez <code>src/App.tsx</code> et enregistrez pour recharger
           </>
         ),
         es: (
           <>
             Edita <code>src/App.tsx</code> y guarda para recargar
           </>
         ),
       }),
       reactLink: {
         href: "https://reactjs.org",
         content: t({
           en: "Learn React",
           fr: "Apprendre React",
           es: "Aprender React",
         }),
       },
     },
   } satisfies Dictionary;
   
   export default appContent;
   

   Suas declarações de conteúdo podem ser definidas em qualquer lugar da sua aplicação, desde que estejam incluídas no diretório contentDir (por padrão, ./src). E correspondam à extensão do arquivo de declaração de conteúdo (por padrão, .content.{json,ts,tsx,js,jsx,mjs,cjs,md,mdx,yaml,yml}).

   Para mais detalhes, consulte a documentação de declaração de conteúdo.

   Se o seu arquivo de conteúdo incluir código TSX, você deve considerar importar import React from "react"; no seu arquivo de conteúdo.

5. 5

   Utilize o Intlayer no Seu Código

   Acesse seus dicionários de conteúdo em toda a sua aplicação:

   src/App.tsx

   Copiar conteúdo

   Copiar código

   Copiar o código para a área de transferência

   import logo from "./logo.svg";
   import "./App.css";
   import type { FC } from "react";
   import { IntlayerProvider, useIntlayer } from "react-intlayer";
   
   const AppContent: FC = () => {
     const content = useIntlayer("app");
   
     return (
       <div className="App">
         <img src={logo} className="App-logo" alt="logo" />
   
         {content.getStarted}
         <a
           className="App-link"
           href={content.reactLink.href.value}
           target="_blank"
           rel="noopener noreferrer"
         >
           {content.reactLink.content}
         </a>
       </div>
     );
   };
   
   const App: FC = () => (
     <IntlayerProvider>
       <AppContent />
     </IntlayerProvider>
   );
   
   export default App;
   

   Nota: Se você quiser usar seu conteúdo em um atributo string, como alt, title, href, aria-label, etc., você deve chamar o valor da função, como:

   html

   Copiar conteúdo

   Copiar código

   Copiar o código para a área de transferência

   <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)}" />
   

   Para saber mais sobre o hook useIntlayer, consulte a documentação.

   Para saber mais sobre o hook useIntlayer, consulte a documentação.

6. 6

   Alterar o idioma do seu conteúdo

   Opcional

   Para alterar o idioma do seu conteúdo, você pode usar a função setLocale fornecida pelo hook useLocale. Essa função permite definir o idioma da aplicação e atualizar o conteúdo de acordo.

   src/components/LocaleSwitcher.tsx

   Copiar conteúdo

   Copiar código

   Copiar o código para a área de transferência

   import { Locales } from "intlayer";
   import { useLocale } from "react-intlayer";
   
   const LocaleSwitcher = () => {
     const { setLocale } = useLocale();
   
     return (
       <button onClick={() => setLocale(Locales.English)}>
         Change Language to English
       </button>
     );
   };
   

   Para saber mais sobre o hook useLocale, consulte a documentação.

7. 7

   Adicionar Rotas Localizadas à sua aplicação

   Opcional

   O objetivo deste passo é criar rotas únicas para cada idioma. Isso é útil para SEO e URLs amigáveis para SEO. Exemplo:

   plaintext

   Copiar conteúdo

   Copiar código

   Copiar o código para a área de transferência

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

   Por padrão, as rotas não são prefixadas para o idioma padrão. Se você quiser prefixar o idioma padrão, pode definir a opção middleware.prefixDefault como true na sua configuração. Consulte a documentação de configuração para mais informações.

   Para adicionar rotas localizadas à sua aplicação, você pode criar um componente LocaleRouter que encapsula as rotas da sua aplicação e gerencia o roteamento baseado no idioma. Aqui está um exemplo usando o React Router:

   src/components/LocaleRouter.tsx

   Copiar conteúdo

   Copiar código

   Copiar o código para a área de transferência

   // Importação de dependências e funções necessárias
   import { type Locales, configuration, getPathWithoutLocale } from "intlayer"; // Funções utilitárias e tipos do 'intlayer'
   // Funções utilitárias e tipos do 'intlayer'
   import type { FC, PropsWithChildren } from "react"; // Tipos React para componentes funcionais e props
   import { IntlayerProvider } from "react-intlayer"; // Provedor para contexto de internacionalização
   import {
     BrowserRouter,
     Routes,
     Route,
     Navigate,
     useLocation,
   } from "react-router-dom"; // Componentes de roteamento para gerenciar navegação
   
   // Desestruturação da configuração do Intlayer
   const { internationalization, middleware } = configuration;
   const { locales, defaultLocale } = internationalization;
   
   /**
    * Um componente que gerencia a localização e encapsula os filhos com o contexto de idioma apropriado.
    * Ele gerencia a detecção e validação do idioma baseada na URL.
    */
   const AppLocalized: FC<PropsWithChildren<{ locale: Locales }>> = ({
     children,
     locale,
   }) => {
     const { pathname, search } = useLocation(); // Obtém o caminho atual da URL
   
     // Determina o idioma atual, retornando ao padrão se não for fornecido
     const currentLocale = locale ?? defaultLocale;
   
     // Remove o prefixo de idioma do caminho para construir um caminho base
     const pathWithoutLocale = getPathWithoutLocale(
       pathname // Caminho atual da URL
     );
   
     /**
      * Se middleware.prefixDefault for verdadeiro, o idioma padrão deve sempre ser prefixado.
      */
     if (middleware.prefixDefault) {
       // Valida o idioma
       if (!locale || !locales.includes(locale)) {
         // Redireciona para o idioma padrão com o caminho atualizado
         return (
           <Navigate
             to={`/${defaultLocale}/${pathWithoutLocale}${search}`}
             replace // Substitui a entrada atual do histórico pela nova
           />
         );
       }
   
       // Encapsula os filhos com o IntlayerProvider e define o idioma atual
       return (
         <IntlayerProvider locale={currentLocale}>{children}</IntlayerProvider>
       );
     } else {
       /**
        * Quando middleware.prefixDefault é falso, o idioma padrão não é prefixado.
        * Garante que o idioma atual seja válido e não o idioma padrão.
        */
       if (
         currentLocale.toString() !== defaultLocale.toString() &&
         !locales
           .filter(
             (locale) => locale.toString() !== defaultLocale.toString() // Exclui o idioma padrão
           )
           .includes(currentLocale) // Verifica se o idioma atual está na lista de idiomas válidos
       ) {
         // Redireciona para o caminho sem prefixo de idioma
         return <Navigate to={`${pathWithoutLocale}${search}`} replace />;
       }
   
       // Encapsula os filhos com o IntlayerProvider e define o idioma atual
       return (
         <IntlayerProvider locale={currentLocale}>{children}</IntlayerProvider>
       );
     }
   };
   
   /**
    * Um componente de roteador que configura rotas específicas para idiomas.
    * Ele usa o React Router para gerenciar a navegação e renderizar componentes localizados.
    */
   export const LocaleRouter: FC<PropsWithChildren> = ({ children }) => (
     <BrowserRouter>
       <Routes>
         {locales
           .filter(
             (locale) => middleware.prefixDefault || locale !== defaultLocale
           )
           .map((locale) => (
             <Route
               // Padrão de rota para capturar o idioma (por exemplo, /en/, /fr/) e corresponder a todos os caminhos subsequentes
               path={`/${locale}/*`}
               key={locale}
               element={<AppLocalized locale={locale}>{children}</AppLocalized>} // Encapsula os filhos com gerenciamento de idioma
             />
           ))}
   
         {
           // Se o prefixo do idioma padrão estiver desativado, renderiza os filhos diretamente no caminho raiz
           !middleware.prefixDefault && (
             <Route
               path="*"
               element={
                 <AppLocalized locale={defaultLocale}>{children}</AppLocalized>
               } // Encapsula os filhos com gerenciamento de idioma
             />
           )
         }
       </Routes>
     </BrowserRouter>
   );
   

   Em seguida, você pode usar o componente LocaleRouter na sua aplicação:

   src/App.tsx

   Copiar conteúdo

   Copiar código

   Copiar o código para a área de transferência

   import { LocaleRouter } from "./components/LocaleRouter";
   import type { FC } from "react";
   
   // ... Seu componente AppContent
   
   const App: FC = () => (
     <LocaleRouter>
       <AppContent />
     </LocaleRouter>
   );
   

8. 8

   Alterar a URL quando o idioma muda

   Opcional

   Para alterar a URL quando o idioma muda, você pode usar a prop onLocaleChange fornecida pelo hook useLocale. Paralelamente, você pode usar os hooks useLocation e useNavigate do react-router-dom para atualizar o caminho da URL.

   src/components/LocaleSwitcher.tsx

   Copiar conteúdo

   Copiar código

   Copiar o código para a área de transferência

   import { useLocation, useNavigate } from "react-router-dom";
   import {
     Locales,
     getHTMLTextDir,
     getLocaleName,
     getLocalizedUrl,
   } from "intlayer";
   import { useLocale } from "react-intlayer";
   import { type FC } from "react";
   
   const LocaleSwitcher: FC = () => {
     const { pathname, search } = useLocation(); // Obtém o caminho atual da URL. Exemplo: /fr/about?foo=bar
     const navigate = useNavigate();
   
     const { locale, availableLocales, setLocale } = useLocale({
       onLocaleChange: (locale) => {
         // Constrói a URL com o idioma atualizado
         // Exemplo: /es/about?foo=bar
         const pathWithLocale = getLocalizedUrl(`${pathname}${search}`, locale);
   
         // Atualiza o caminho da URL
         navigate(pathWithLocale);
       },
     });
   
     return (
       <div>
         <button popoverTarget="localePopover">{getLocaleName(locale)}</button>
         <div id="localePopover" popover="auto">
           {availableLocales.map((localeItem) => (
             <a
               href={getLocalizedUrl(location.pathname, localeItem)}
               hrefLang={localeItem}
               aria-current={locale === localeItem ? "page" : undefined}
               onClick={(e) => {
                 e.preventDefault();
                 setLocale(localeItem);
               }}
               key={localeItem}
             >
               <span>
                 {/* Idioma - ex: FR */}
                 {localeItem}
               </span>
               <span>
                 {/* Idioma no próprio idioma - ex: Français */}
                 {getLocaleName(localeItem, locale)}
               </span>
               <span dir={getHTMLTextDir(localeItem)} lang={localeItem}>
                 {/* Idioma no idioma atual - ex: Francés com idioma atual definido como Locales.SPANISH */}
                 {getLocaleName(localeItem)}
               </span>
               <span dir="ltr" lang={Locales.ENGLISH}>
                 {/* Idioma em inglês - ex: French */}
                 {getLocaleName(localeItem, Locales.ENGLISH)}
               </span>
             </a>
           ))}
         </div>
       </div>
     );
   };
   

   Referências da documentação:

   • Hook useLocale
   • Hook getLocaleName
   • Hook getLocalizedUrl
   • Hook getHTMLTextDir
   • Atributo hrefLang
   • Atributo lang
   • Atributo dir
   • Atributo aria-current

9. 9

   Alterar os Atributos de Idioma e Direção do HTML

   Opcional

   Quando sua aplicação suporta vários idiomas, é crucial atualizar os atributos lang e dir da tag <html> para corresponder ao idioma atual. Isso garante:

   • Acessibilidade: Leitores de tela e tecnologias assistivas dependem do atributo lang correto para pronunciar e interpretar o conteúdo com precisão.
   • Renderização de Texto: O atributo dir (direção) garante que o texto seja renderizado na ordem correta (por exemplo, da esquerda para a direita para inglês, da direita para a esquerda para árabe ou hebraico), o que é essencial para a legibilidade.
   • SEO: Os motores de busca usam o atributo lang para determinar o idioma da sua página, ajudando a servir o conteúdo localizado correto nos resultados de busca.

   Ao atualizar esses atributos dinamicamente quando o idioma muda, você garante uma experiência consistente e acessível para os usuários em todos os idiomas suportados.

   Implementando o Hook

   Crie um hook personalizado para gerenciar os atributos HTML. O hook escuta as mudanças de idioma e atualiza os atributos de acordo:

   src/hooks/useI18nHTMLAttributes.tsx

   Copiar conteúdo

   Copiar código

   Copiar o código para a área de transferência

   /**
    * Atualiza os atributos `lang` e `dir` do elemento HTML <html> com base no idioma atual.
    * - `lang`: Informa navegadores e motores de busca sobre o idioma da página.
    * - `dir`: Garante a ordem de leitura correta (por exemplo, 'ltr' para inglês, 'rtl' para árabe).
    *
    * Essa atualização dinâmica é essencial para renderização de texto adequada, acessibilidade e SEO.
    */
   export const useI18nHTMLAttributes = () => {
     const { locale } = useLocale();
   
     useEffect(() => {
       // Atualiza o atributo de idioma para o idioma atual.
       document.documentElement.lang = locale;
   
       // Define a direção do texto com base no idioma atual.
       document.documentElement.dir = getHTMLTextDir(locale);
     }, [locale]);
   };
   

   Usando o Hook na Sua Aplicação

   Integre o hook no seu componente principal para que os atributos HTML sejam atualizados sempre que o idioma mudar:

   src/App.tsx

   Copiar conteúdo

   Copiar código

   Copiar o código para a área de transferência

   import type { FC } from "react";
   import { IntlayerProvider, useIntlayer } from "react-intlayer";
   import { useI18nHTMLAttributes } from "./hooks/useI18nHTMLAttributes";
   import "./App.css";
   
   const AppContent: FC = () => {
     // Aplica o hook para atualizar os atributos lang e dir da tag <html> com base no idioma.
     useI18nHTMLAttributes();
   
     // ... Resto do seu componente
   };
   
   const App: FC = () => (
     <IntlayerProvider>
       <AppContent />
     </IntlayerProvider>
   );
   
   export default App;
   

   Ao aplicar essas alterações, sua aplicação irá:

   • Garantir que o atributo language (lang) reflita corretamente o idioma atual, o que é importante para SEO e para o comportamento do navegador.
   • Ajustar a direção do texto (dir) de acordo com o idioma, melhorando a legibilidade e usabilidade para idiomas com diferentes ordens de leitura.
   • Proporcionar uma experiência mais acessível, pois tecnologias assistivas dependem desses atributos para funcionar de forma otimizada.

Configurar TypeScript

O Intlayer usa a ampliação de módulos para obter os benefícios do TypeScript e tornar sua base de código mais robusta.

Certifique-se de que sua configuração do TypeScript inclua os tipos autogerados.

{
  // ... Suas configurações existentes do TypeScript
  "include": [
    // ... Suas configurações existentes do TypeScript
    ".intlayer/**/*.ts", // Inclua os tipos autogerados
  ],
}

Configuração do Git

Recomenda-se ignorar os arquivos gerados pelo Intlayer. Isso permite evitar que eles sejam enviados para o seu repositório Git.

Para fazer isso, você pode adicionar as seguintes instruções ao seu arquivo .gitignore:

# Ignore os arquivos gerados pelo Intlayer
.intlayer

Extensão VS Code

Para melhorar sua experiência de desenvolvimento com Intlayer, você pode instalar a extensão oficial Intlayer VS Code Extension.

Para melhorar sua experiência de desenvolvimento com o Intlayer, você pode instalar a Extensão oficial do Intlayer para VS Code. Instale a partir do VS Code Marketplace

Esta extensão oferece:

• Autocompletar para chaves de tradução.
• Detecção de erros em tempo real para traduções ausentes.
• Visualizações inline do conteúdo traduzido.
• Ações rápidas para criar e atualizar traduções facilmente.

Para mais detalhes sobre como usar a extensão, consulte a documentação da extensão Intlayer para VS Code.

Avançar

Para avançar, você pode implementar o editor visual ou externalizar seu conteúdo usando o CMS.

Perguntas Frequentes