Traduza seu site Vite e Preact usando o Intlayer | Internacionalização (i18n)

Tabela de Conteúdos

Por que Intlayer em vez de alternativas?

Comparado com soluções principais como preact-i18n ou i18next, Intlayer é uma solução que vem com otimizações integradas como:

Guia Passo a Passo para Configurar o Intlayer em uma Aplicação Vite e Preact

Veja o Modelo de Aplicação no GitHub.

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 preact-intlayer
   npm install vite-intlayer --save-dev
   

   • intlayer

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

   • preact-intlayer O pacote que integra o Intlayer com a aplicação Preact. Ele fornece provedores de contexto e hooks para internacionalização em Preact.

   • vite-intlayer Inclui o plugin Vite para integrar o Intlayer com o empacotador Vite, bem como middleware para detectar a localidade preferida do usuário, gerenciar cookies e lidar com redirecionamento de URL.

2. 2

   Configuração do seu projeto

   Arquitetura

   Nesta arquitetura, o preact-intlayer fornece o IntlayerProvider montado em main.tsx para envolver a árvore Preact. As declarações de conteúdo ficam em src/ ao lado dos componentes.

   bash

   Copiar conteúdo

   Copiar código

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

   .
   ├── src
   │   ├── app.content.tsx
   │   ├── app.css
   │   ├── app.tsx                       # Main Preact application component
   │   ├── components
   │   │   ├── LocaleSwitcher.content.ts
   │   │   └── LocaleSwitcher.tsx
   │   ├── main.tsx                      # Entry point with IntlayerProvider
   │   └── vite-env.d.ts
   ├── index.html
   ├── intlayer.config.ts
   ├── package.json
   ├── tsconfig.json
   └── vite.config.ts
   

   Configuração

   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,
     },
     routing: {
       mode: "prefix-no-default", // Padrão: prefixar todos os locais exceto o padrão
       storage: ["cookie", "header"], // Padrão: armazenar locale no cookie e detectar pelo header
     },
   };
   
   export default config;
   

   Através deste arquivo de configuração, você pode configurar URLs localizadas, modos de roteamento, opções de armazenamento, nomes de cookies, a localização e extensão das suas declarações de conteúdo, desabilitar logs do Intlayer no console e muito mais. Para uma lista completa dos parâmetros disponíveis, consulte a documentação de configuração.

3. 3

   Integre o Intlayer na Sua Configuração do Vite

   Adicione o plugin intlayer na sua configuração.

   vite.config.ts

   Copiar conteúdo

   Copiar código

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

   import { defineConfig } from "vite";
   import preact from "@preact/preset-vite";
   import { intlayer } from "vite-intlayer";
   
   // https://vitejs.dev/config/
   export default defineConfig({
     plugins: [preact(), intlayer()],
   });
   

   O plugin Vite intlayer() é usado para integrar o Intlayer com o Vite. Ele garante a construção dos arquivos de declaração de conteúdo e os monitora no modo de desenvolvimento. Define variáveis de ambiente do Intlayer dentro da aplicação Vite. Além disso, fornece aliases para otimizar o desempenho.

4. 4

   Declare 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 type { ComponentChildren } from "preact";
   
   const appContent = {
     key: "app",
     content: {
       viteLogo: t({
         en: "Vite logo",
         fr: "Logo Vite",
         es: "Logo Vite",
       }),
       preactLogo: t({
         en: "Preact logo",
         fr: "Logo Preact",
         es: "Logo Preact",
       }),
   
       title: "Vite + Preact",
   
       count: t({
         en: "count is ",
         fr: "le compte est ",
         es: "el recuento es ",
       }),
   
       edit: t<ComponentChildren>({
         en: (
           <>
             Edit <code>src/app.tsx</code> and save to test HMR
           </>
         ),
         fr: (
           <>
             Éditez <code>src/app.tsx</code> et enregistrez pour tester HMR
           </>
         ),
         es: (
           <>
             Edita <code>src/app.tsx</code> y guarda para probar HMR
           </>
         ),
       }),
   
       readTheDocs: t({
         en: "Click on the Vite and Preact logos to learn more",
         fr: "Cliquez sur les logos Vite et Preact pour en savoir plus",
         es: "Haga clic en los logotipos de Vite y Preact para obtener más información",
       }),
     },
   } 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 seu arquivo de conteúdo incluir código TSX, pode ser necessário importar import { h } from "preact"; ou garantir que sua pragma JSX esteja corretamente configurada para Preact.

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 { useState } from "preact/hooks";
   import type { FunctionalComponent } from "preact";
   import preactLogo from "./assets/preact.svg"; // Supondo que você tenha um preact.svg
   import viteLogo from "/vite.svg";
   import "./app.css"; // Supondo que seu arquivo CSS se chame app.css
   import { IntlayerProvider, useIntlayer } from "preact-intlayer";
   
   const AppContent: FunctionalComponent = () => {
     const [count, setCount] = useState(0);
     const content = useIntlayer("app");
   
     return (
       <>
         <div>
           <a href="https://vitejs.dev" target="_blank">
             <img src={viteLogo} class="logo" alt={content.viteLogo.value} />
           </a>
           <a href="https://preactjs.com" target="_blank">
             <img
               src={preactLogo}
               class="logo preact"
               alt={content.preactLogo.value}
             />
           </a>
         </div>
         <h1>{content.title}</h1>
         <div class="card">
           <button onClick={() => setCount((count) => count + 1)}>
             {content.count}
             {count}
           </button>
           <p>{content.edit}</p>
         </div>
         {/* Conteúdo Markdown */}
         <div>{content.myMarkdownContent}</div>
   
         {/* Conteúdo HTML */}
         <div>{content.myHtmlContent}</div>
   
         <p class="read-the-docs">{content.readTheDocs}</p>
       </>
     );
   };
   
   const App: FunctionalComponent = () => (
     <IntlayerProvider>
       <AppContent />
     </IntlayerProvider>
   );
   
   export default App;
   

   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, assim:

   tsx

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

   Nota: No Preact, className é tipicamente escrito como class.

   Para saber mais sobre o hook useIntlayer, consulte a documentação (A API é semelhante para preact-intlayer).

   Se a sua aplicação já existe, você pode usar o Intlayer Compiler em conjunto com o comando extract para converter milhares de componentes em um segundo.

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 locale 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 type { FunctionalComponent } from "preact";
   import { Locales } from "intlayer";
   import { useLocale } from "preact-intlayer";
   
   const LocaleSwitcher: FunctionalComponent = () => {
     const { setLocale } = useLocale();
   
     return (
       <button onClick={() => setLocale(Locales.ENGLISH)}>
         Alterar idioma para Inglês
       </button>
     );
   };
   
   export default LocaleSwitcher;
   

   Para saber mais sobre o hook useLocale, consulte a documentação (A API é semelhante para preact-intlayer).

7. 7

   Adicionar roteamento por localeizado à 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 routing.mode como "prefix-all" na sua configuração. Veja a documentação de configuração para mais informações.

   Para adicionar roteamento por localeizado à sua aplicação, você pode criar um componente LocaleRouter que envolva as rotas da sua aplicação e gerencie o roteamento baseado no idioma. Aqui está um exemplo usando preact-iso :

   src/components/LocaleRouter.tsx

   Copiar conteúdo

   Copiar código

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

   import { localeMap } from "intlayer";
   import { IntlayerProvider } from "preact-intlayer";
   import { LocationProvider, Router, Route } from "preact-iso";
   import type { ComponentChildren, FunctionalComponent } from "preact";
   
   /**
    * Um componente de roteador que configura rotas específicas para cada locale.
    * Ele usa preact-iso para gerenciar a navegação e renderizar componentes localizados.
    */
   export const LocaleRouter: FunctionalComponent<{
     children: ComponentChildren;
   }> = ({ children }) => (
     <LocationProvider>
       <Router>
         {localeMap(({ locale, urlPrefix }) => ({ locale, urlPrefix }))
           .sort((a, b) => b.urlPrefix.length - a.urlPrefix.length)
           .map(({ locale, urlPrefix }) => (
             <Route
               key={locale}
               path={`${urlPrefix}/:rest*`}
               component={() => (
                 <IntlayerProvider locale={locale}>{children}</IntlayerProvider>
               )}
             />
           ))}
       </Router>
     </LocationProvider>
   );
   

   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 { FunctionalComponent } from "preact";
   
   // ... Seu componente AppContent
   
   const App: FunctionalComponent = () => (
     <LocaleRouter>
       <AppContent />
     </LocaleRouter>
   );
   
   export default App;
   

   Em paralelo, você também pode usar o intlayerProxy para adicionar roteamento do lado do servidor à sua aplicação. Este plugin detectará automaticamente a localidade atual com base na URL e definirá o cookie de localidade apropriado. Se nenhuma localidade for especificada, o plugin determinará a localidade mais apropriada com base nas preferências de idioma do navegador do usuário. Se nenhuma localidade for detectada, ele redirecionará para a localidade padrão.

   Observe que para usar o intlayerProxy em produção, você precisa mudar o pacote vite-intlayer de devDependencies para dependencies.

   Desde Intlayer v9, intlayerProxy() é incluído diretamente no plugin intlayer() e ativado 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. Defina routing.enableProxy: false para desativar. Veja as notas de lançamento da v9.

   vite.config.ts

   Copiar conteúdo

   Copiar código

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

   import { defineConfig } from "vite";
   import { intlayer } from "vite-intlayer";
   import preact from "@preact/preset-vite";
   
   // https://vitejs.dev/config/
   export default defineConfig({
     plugins: [
       preact(),
       intlayer({
         proxy: {
           ignore: (req) => req.url?.startsWith("/api"),
         },
       }),
     ],
   });
   

8. 8

   Alterar a URL quando o idioma mudar

   Opcional

   Para alterar a URL quando o locale mudar, você pode usar a prop onLocaleChange fornecida pelo hook useLocale. Em paralelo, você pode usar o método route do useLocation do preact-iso 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 } from "preact-iso";
   import {
     Locales,
     getHTMLTextDir,
     getLocaleName,
     getLocalizedUrl,
   } from "intlayer";
   import { useLocale } from "preact-intlayer";
   import type { FunctionalComponent } from "preact";
   
   const LocaleSwitcher: FunctionalComponent = () => {
     const { url, route } = useLocation();
     const { locale, availableLocales, setLocale } = useLocale({
       onLocaleChange: (newLocale) => {
         // Construir a URL com o locale atualizado
         // Exemplo: /es/about?foo=bar
         const pathWithLocale = getLocalizedUrl(url, newLocale);
   
         // Atualizar o caminho da URL
         route(pathWithLocale, true); // true para substituir
       },
     });
   
     return (
       <div>
         <button popovertarget="localePopover">{getLocaleName(locale)}</button>
         <div id="localePopover" popover="auto">
           {availableLocales.map((localeItem) => (
             <a
               href={getLocalizedUrl(url, localeItem)}
               hreflang={localeItem}
               aria-current={locale === localeItem ? "page" : undefined}
               onClick={(e) => {
                 e.preventDefault();
                 setLocale(localeItem);
                 // A navegação programática após definir o locale será tratada por onLocaleChange
               }}
               key={localeItem}
             >
               <span>
                 {/* Locale - ex: FR */}
                 {localeItem}
               </span>
               <span>
                 {/* Idioma no seu próprio Locale - ex: Français */}
                 {getLocaleName(localeItem, localeItem)}
               </span>
               <span dir={getHTMLTextDir(localeItem)} lang={localeItem}>
                 {/* Idioma no Locale atual - ex: Francés com o locale atual definido como Locales.SPANISH */}
                 {getLocaleName(localeItem, locale)}
               </span>
               <span dir="ltr" lang={Locales.ENGLISH}>
                 {/* Idioma em Inglês - ex: French */}
                 {getLocaleName(localeItem, Locales.ENGLISH)}
               </span>
             </a>
           ))}
         </div>
       </div>
     );
   };
   
   export default LocaleSwitcher;
   

   Referências da documentação:

   - Hook useLocale (API é semelhante para preact-intlayer)> - Hook getLocaleName> - Hook getLocalizedUrl> - Hook getHTMLTextDir> - Atributo hreflang> - Atributo lang> - Atributo dir> - Atributo aria-current> - API Popover

   Abaixo está o Passo 9 atualizado com explicações adicionadas e exemplos de código refinados:

9. 9

   Alternar os atributos de idioma e direção do HTML

   Opcional

   Quando sua aplicação suporta múltiplos idiomas, é crucial atualizar os atributos lang e dir da tag <html> para corresponder ao locale atual. Fazer 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) assegura 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 utilizam o atributo lang para determinar o idioma da sua página, ajudando a exibir o conteúdo localizado correto nos resultados de pesquisa.

   Ao atualizar esses atributos dinamicamente quando o locale 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 locale e atualiza os atributos conforme necessário:

   src/hooks/useI18nHTMLAttributes.tsx

   Copiar conteúdo

   Copiar código

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

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

   src/app.tsx

   Copiar conteúdo

   Copiar código

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

   import type { FunctionalComponent } from "preact";
   import { IntlayerProvider } from "preact-intlayer"; // useIntlayer já importado se AppContent precisar
   import { useI18nHTMLAttributes } from "./hooks/useI18nHTMLAttributes";
   import "./app.css";
   // Definição do AppContent a partir do Passo 5
   
   const AppWithHooks: FunctionalComponent = () => {
     // Aplicar o hook para atualizar os atributos lang e dir da tag <html> com base no locale.
     useI18nHTMLAttributes();
   
     // Supondo que AppContent seja seu componente principal de exibição de conteúdo do Passo 5
     return <AppContent />;
   };
   
   const App: FunctionalComponent = () => (
     <IntlayerProvider>
       <AppWithHooks />
     </IntlayerProvider>
   );
   
   export default App;
   

   Ao aplicar essas mudanças, sua aplicação irá:

   • Certifique-se de que o atributo language (lang) reflita corretamente a localidade atual, o que é importante para SEO e comportamento do navegador.
   • Ajuste a direção do texto (dir) de acordo com a localidade, melhorando a legibilidade e usabilidade para idiomas com ordens de leitura diferentes.
   • Forneça uma experiência mais acessível, pois as tecnologias assistivas dependem desses atributos para funcionar otimamente.
10. 10

    Criando um componente de link localizado

    Opcional

    Para garantir que a navegação da sua aplicação respeite o locale atual, você pode criar um componente Link personalizado. Este componente prefixa automaticamente as URLs internas com o idioma atual.

    Este comportamento é útil por vários motivos:

    • SEO e Experiência do Usuário: URLs localizadas ajudam os motores de busca a indexar corretamente as páginas específicas por idioma e fornecem aos usuários conteúdo no idioma de sua preferência.
    • Consistência: Ao usar um link localizado em toda a sua aplicação, você garante que a navegação permaneça dentro do locale atual, evitando mudanças inesperadas de idioma.
    • Manutenibilidade: Centralizar a lógica de localização em um único componente simplifica a gestão das URLs.

    Abaixo está a implementação de um componente Link localizado em Preact:

    src/components/Link.tsx

    Copiar conteúdo

    Copiar código

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

    import { getLocalizedUrl } from "intlayer";
    import { useLocale } from "preact-intlayer";
    import { forwardRef } from "preact/compat";
    import type { JSX } from "preact";
    
    export interface LinkProps extends JSX.HTMLAttributes<HTMLAnchorElement> {
      href: string;
    }
    
    /**
     * Função utilitária para verificar se uma URL dada é externa.
     * Se a URL começar com http:// ou https://, ela é considerada externa.
     */
    export const checkIsExternalLink = (href?: string): boolean =>
      /^https?:\/\//.test(href ?? "");
    
    /**
     * Um componente Link personalizado que adapta o atributo href com base no locale atual.
     * Para links internos, ele usa `getLocalizedUrl` para prefixar a URL com o locale (ex: /fr/about).
     * Isso garante que a navegação permaneça dentro do mesmo contexto de locale.
     */
    export const Link = forwardRef<HTMLAnchorElement, LinkProps>(
      ({ href, children, ...props }, ref) => {
        const { locale } = useLocale();
        const isExternalLink = checkIsExternalLink(href);
    
        // Se o link for interno e um href válido for fornecido, obtenha a URL localizada.
        const hrefI18n =
          href && !isExternalLink ? getLocalizedUrl(href, locale) : href;
    
        return (
          <a href={hrefI18n} ref={ref} {...props}>
            {children}
          </a>
        );
      }
    );
    
    Link.displayName = "Link";
    

    Como Funciona

    • Detectando Links Externos:
      A função auxiliar checkIsExternalLink determina se uma URL é externa. Links externos permanecem inalterados porque não precisam de localização.
    • Recuperando o Locale Atual:
      O hook useLocale fornece o locale atual (ex: fr para francês).
    • Localizando a URL:
      Para links internos (ou seja, não externos), o getLocalizedUrl é usado para prefixar automaticamente a URL com o locale atual. Isso significa que, se o seu usuário estiver em francês, passar /about como o href o transformará em /fr/about.
    • Retornando o Link:
      O componente retorna um elemento <a> com a URL localizada, garantindo que a navegação seja consistente com o locale.
11. 11

    Renderizar Markdown e HTML

    Opcional

    O Intlayer suporta a renderização de conteúdo Markdown e HTML no Preact.

    Você pode personalizar a renderização de conteúdo Markdown e HTML usando o método .use(). Este método permite que você substitua a renderização padrão de tags específicas.

    tsx

    Copiar conteúdo

    Copiar código

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

    import { useIntlayer } from "preact-intlayer";
    
    const { myMarkdownContent, myHtmlContent } = useIntlayer("my-component");
    
    // ...
    
    return (
      <div>
        {/* Renderização básica */}
        {myMarkdownContent}
    
        {/* Renderização personalizada para Markdown */}
        {myMarkdownContent.use({
          h1: (props) => <h1 style={{ color: "red" }} {...props} />,
        })}
    
        {/* Renderização básica para HTML */}
        {myHtmlContent}
    
        {/* Renderização personalizada para HTML */}
        {myHtmlContent.use({
          b: (props) => <strong style={{ color: "blue" }} {...props} />,
        })}
      </div>
    );
    

12. 1

    Extrair o conteúdo dos seus componentes

    Opcional

    Se você tiver uma base de código existente, transformar milhares de arquivos pode ser demorado.

    Para facilitar esse processo, o Intlayer propõe um compilador / extrator para transformar seus componentes e extrair o conteúdo.

    Para configurá-lo, você pode adicionar uma seção compiler no seu arquivo intlayer.config.ts:

    intlayer.config.ts

    Copiar conteúdo

    Copiar código

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

    import { type IntlayerConfig } from "intlayer";
    
    const config: IntlayerConfig = {
      // ... Resto da sua configuração
      compiler: {
        /**
         * Indica se o compilador deve ser ativado.
         */
        enabled: true,
    
        /**
         * Define o caminho dos arquivos de saída
         */
        output: ({ fileName, extension }) => `./${fileName}${extension}`,
    
        /**
         * Indica se os componentes devem ser salvos após serem transformados. Dessa forma, o compilador pode ser executado apenas uma vez para transformar o aplicativo e depois removido.
         */
        saveComponents: false,
    
        /**
         * Prefixo da chave do dicionário
         */
        dictionaryKeyPrefix: "",
      },
    };
    
    export default config;
    

    Comando de extraçãoCompilador Babel

    Execute o extrator para transformar seus componentes e extrair o conteúdo

    bash

    Copiar conteúdo

    Copiar código

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

    npx intlayer extract
    

    Since v9, the intlayerCompiler is included in the intlayer plugin. So you don't need to add it manually.

    Atualize seu vite.config.ts para incluir o plugin intlayerCompiler:

    vite.config.ts

    Copiar conteúdo

    Copiar código

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

    import { defineConfig } from "vite";
    import { intlayer, intlayerCompiler } from "vite-intlayer";
    
    export default defineConfig({
      plugins: [
        intlayer(),
        intlayerCompiler(), // Adds the compiler plugin
      ],
    });
    

    bash

    Copiar conteúdo

    Copiar código

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

    npm run build # Ou npm run dev
    

(Opcional) Sitemap e robots.txt (geração no build)

A Intlayer expõe utilitários - generateSitemap e getMultilingualUrls - para formatar um sitemap.xml multilíngue e um robots.txt prontos para crawlers e os gravar automaticamente em public/. Normalmente corre um pequeno script Node antes do Vite (por exemplo hooks npm predev / prebuild) para que os ficheiros existam no build ou no servidor de desenvolvimento.

Sitemap

O gerador de sitemaps da Intlayer respeita as suas línguas e inclui os metadados habituais.

O sitemap suporta o espaço de nomes xhtml:link (hreflang). Em vez de listar apenas URLs soltas, a Intlayer liga de forma bidireccional todas as versões localizadas de cada página (por exemplo /about, /fr/about ou /about?lang=fr consoante o modo de rotas).

Robots.txt

Use getMultilingualUrls para que as regras Disallow cubram todas as variantes localizadas de caminhos sensíveis.

1. Criar generate-seo.mjs na raiz do projeto

import fs from "fs";
import path from "path";
import { fileURLToPath } from "url";
import { generateSitemap, getMultilingualUrls } from "intlayer";

const __dirname = path.dirname(fileURLToPath(import.meta.url));

const SITE_URL = (process.env.SITE_URL || "http://localhost:5173").replace(
  /\/$/,
  ""
);

const pathList = [
  { path: "/", changefreq: "daily", priority: 1.0 },
  { path: "/about", changefreq: "monthly", priority: 0.7 },
];

const sitemapXml = generateSitemap(pathList, { siteUrl: SITE_URL });
fs.writeFileSync(path.join(__dirname, "public", "sitemap.xml"), sitemapXml);

const getAllMultilingualUrls = (urls) =>
  urls.flatMap((url) => Object.values(getMultilingualUrls(url)));

const disallowedPaths = getAllMultilingualUrls(["/admin", "/private"]);

const robotsTxt = [
  "User-agent: *",
  "Allow: /",
  ...disallowedPaths.map((path) => `Disallow: ${path}`),
  "",
  `Sitemap: ${SITE_URL}/sitemap.xml`,
].join("\n");

fs.writeFileSync(path.join(__dirname, "public", "robots.txt"), robotsTxt);

console.log("SEO files generated successfully.");

O pacote intlayer tem de estar instalado. Defina SITE_URL no ambiente em produção (por exemplo na CI).

Prefira generate-seo.mjs para ESM no Node. Se usar generate-seo.js, garanta "type": "module" no package.json ou execute o Node com ESM.

2. Executar o script antes do Vite

{
  "scripts": {
    "dev": "vite",
    "prebuild": "node generate-seo.mjs",
    "build": "vite build",
    "preview": "vite preview"
  }
}

Ajuste os comandos se usar pnpm ou yarn. Também pode invocar o script a partir da CI ou de outro passo do pipeline.

Configurar TypeScript

O Intlayer usa aumento de módulo para obter benefícios do TypeScript e tornar sua base de código mais forte.

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

{
  // ... Suas configurações de TypeScript existentes
  "compilerOptions": {
    // ...
    "jsx": "react-jsx",
    "jsxImportSource": "preact", // Recomendado para Preact 10+
    // ...
  },
  "include": [
    // ... Suas configurações de TypeScript existentes
    ".intlayer/**/*.ts", // Inclua os tipos autogerados
  ],
}

Certifique-se de que seu tsconfig.json esteja configurado para o Preact, especialmente jsx e jsxImportSource ou jsxFactory/jsxFragmentFactory para versões antigas do Preact, se não estiver usando os padrões do preset-vite.

Configuração do Git

Recomenda-se ignorar os arquivos gerados pelo Intlayer. Isso permite que você evite comitá-los em seu repositório Git.

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

# Ignore the files generated by Intlayer
.intlayer

Extensão do VS Code

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

Instalar a partir do VS Code Marketplace

Esta extensão fornece:

• Autocomplemento 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.

Ir Mais Longe

Para ir mais longe, você pode implementar o editor visual ou externalizar seu conteúdo usando o CMS.

Perguntas Frequentes