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

Índice

Por que Intlayer em vez de alternativas?

Comparado com soluções principais como svelte-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 Svelte

Veja o Template da 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 svelte-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.

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

   • vite-intlayer Inclui o plugin Vite para integrar o Intlayer com o bundler Vite, assim como middleware para detectar o locale preferido do usuário, gerenciar cookies e lidar com redirecionamento de URL.

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 locales
       ],
       defaultLocale: Locales.ENGLISH,
     },
   };
   
   export default config;
   

   Através deste arquivo de configuração, você pode configurar URLs localizadas, redirecionamento de middleware, 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 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 { svelte } from "@sveltejs/vite-plugin-svelte";
   import { intlayer } from "vite-intlayer";
   
   // https://vitejs.dev/config/
   export default defineConfig({
     plugins: [svelte(), intlayer()],
   });
   

   O plugin intlayer() para Vite é 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 as 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";
   
   const appContent = {
     key: "app",
     content: {
       title: t({
         en: "Hello World",
         fr: "Bonjour le monde",
         es: "Hola mundo",
       }),
     },
   } satisfies Dictionary;
   
   export default appContent;
   

   Suas declarações de conteúdo podem ser definidas em qualquer lugar da sua aplicação assim que forem incluídas no diretório contentDir (por padrão, ./src). E devem corresponder à 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.

5. 5

   Utilize o Intlayer no Seu Código

   src/App.svelte

   Copiar conteúdo

   Copiar código

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

   <script>
     import { useIntlayer } from "svelte-intlayer";
   
     const content = useIntlayer("app");
   </script>
   
   <div>
   
   
   <!-- Renderizar conteúdo como conteúdo simples -->
   <h1>{$content.title}</h1>
   <!-- Para renderizar o conteúdo editável usando o editor -->
   <h1>{@const Title = $content.title}<Title /></h1>
   <!-- Para renderizar o conteúdo como uma string -->
   <div aria-label={$content.title.value}></div>
   <div aria-label={$content.title.toString()}></div>
   <div aria-label={String($content.title)}></div>
   
   > Se a sua aplicação já existe, você pode usar o [Intlayer Compiler](/pt/doc/compiler) em conjunto com o [comando extract](/pt/doc/concept/cli/extract) para converter milhares de componentes em um segundo.
   

   Se sua aplicação já existe, você pode usar o Intlayer Compiler, bem como o comando extract, para transformar milhares de componentes em um segundo.

6. 6

   Alterar o idioma do seu conteúdo

   Opcional

   src/App.svelte

   Copiar conteúdo

   Copiar código

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

   <script lang="ts">
   import  { getLocaleName } from 'intlayer';
   import { useLocale } from "svelte-intlayer";
   
   // Obter informações do locale e função setLocale
   const { locale, availableLocales, setLocale } = useLocale();
   
   // Manipular mudança de locale
   const changeLocale = (event: Event) => {
     const target = event.target as HTMLSelectElement;
     const newLocale = target.value;
     setLocale(newLocale);
   };
   </script>
   
   <div>
     <select value={$locale} on:change={changeLocale}>
       {#each availableLocales ?? [] as loc}
         <option value={loc}>
           {getLocaleName(loc)}
         </option>
       {/each}
     </select>
   </div>
   

7. 7

   Renderizar Markdown

   Opcional

   O Intlayer suporta a renderização de conteúdo Markdown diretamente na sua aplicação Svelte. Por padrão, o Markdown é tratado como texto simples. Para converter Markdown em HTML enriquecido, você pode integrar @humanspeak/svelte-markdown ou outro parser de markdown.

   Para ver como declarar conteúdo markdown usando o pacote intlayer, consulte a documentação de markdown.

   src/App.svelte

   Copiar conteúdo

   Copiar código

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

   <script>
     import { setIntlayerMarkdown } from "svelte-intlayer";
   
     setIntlayerMarkdown((markdown) =>
      // renderizar o conteúdo markdown como uma string
      return markdown;
     );
   </script>
   
   <h1>{$content.markdownContent}</h1>
   

   Você também pode acessar os dados do front-matter do seu markdown usando a propriedade content.markdownContent.metadata.xxx.

8. 8

   Configurar o editor / CMS do intlayer

   Opcional

   Para configurar o editor do intlayer, você deve seguir a documentação do editor intlayer.

   Para configurar o CMS do intlayer, você deve seguir a documentação do CMS intlayer.

9. 7

   Adicionar roteamento por localeizado à sua aplicação

   Opcional

   Para lidar com roteamento por localeizado na sua aplicação Svelte, você pode usar o svelte-spa-router junto com o localeFlatMap do Intlayer para gerar rotas para cada localidade.

   Primeiro, instale o svelte-spa-router:

   bash

   Copiar conteúdo

   Copiar código

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

   npm install svelte-spa-router
   npx intlayer init
   

   Então, crie um arquivo Router.svelte para definir suas rotas:

   src/Router.svelte

   Copiar conteúdo

   Copiar código

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

   <script lang="ts">
   import { localeFlatMap } from "intlayer";
   import Router from "svelte-spa-router";
   import { wrap } from "svelte-spa-router/wrap";
   import App from "./App.svelte";
   
   const routes = Object.fromEntries(
       localeFlatMap(({locale, urlPrefix}) => [
       [
           urlPrefix || '/',
           wrap({
               component: App as any,
               props: {
                   locale,
               },
           }),
       ],
       ])
   );
   </script>
   
   <Router {routes} />
   

   Atualize seu main.ts para montar o componente Router em vez do App:

   src/main.ts

   Copiar conteúdo

   Copiar código

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

   import { mount } from "svelte";
   import Router from "./Router.svelte";
   
   const app = mount(Router, {
     target: document.getElementById("app")!,
   });
   
   export default app;
   

   Finalmente, atualize seu App.svelte para receber a prop locale e usá-la com useIntlayer:

   src/App.svelte

   Copiar conteúdo

   Copiar código

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

   <script lang="ts">
   import type { Locale } from 'intlayer';
   import { useIntlayer } from "svelte-intlayer";
   import Counter from './lib/Counter.svelte';
   import LocaleSwitcher from './lib/LocaleSwitcher.svelte';
   
   export let locale: Locale;
   
   $: content = useIntlayer('app', locale);
   </script>
   
   <main>
     <div class="locale-switcher-container">
       <LocaleSwitcher currentLocale={locale} />
     </div>
   
     <!-- ... resto da sua aplicação ... -->
   </main>
   

   Configurar Roteamento no Lado do Servidor (Opcional)

   Paralelamente, você também pode usar o intlayerProxy para adicionar roteamento do lado do servidor à sua aplicação. Este plugin detectará automaticamente o locale atual com base na URL e definirá o cookie de locale apropriado. Se nenhum locale for especificado, o plugin determinará o locale mais adequado com base nas preferências de idioma do navegador do usuário. Se nenhum locale for detectado, ele redirecionará para o locale padrão.

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

   Desde o Intlayer v9, intlayerProxy() está agrupado diretamente no plugin intlayer() e ativado por padrão através da opção routing.enableProxy (true por padrão). Registrá-lo separadamente conforme mostrado abaixo agora é opcional — é mantido para compatibilidade com versões anteriores e para configurações que precisam controlar a ordem dos plugins. Defina routing.enableProxy: false para desativar. Veja as notas de lançamento 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 { svelte } from "@sveltejs/vite-plugin-svelte";
   import { intlayer } from "vite-intlayer";
   
     plugins: [intlayerProxy(), // should be placed first
    svelte(), intlayer()],
   });
   

10. 8

    Alterar a URL quando o locale mudar

    Opcional

    Para permitir que os usuários mudem de idioma e atualizem a URL de acordo, você pode criar um componente LocaleSwitcher. Este componente usará getLocalizedUrl do intlayer e push do svelte-spa-router.

    src/lib/LocaleSwitcher.svelte

    Copiar conteúdo

    Copiar código

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

    <script lang="ts">
    import { getLocaleName, getLocalizedUrl } from "intlayer";
    import { useLocale } from "svelte-intlayer";
    import { push } from "svelte-spa-router";
    
    export let currentLocale: string | undefined = undefined;
    
    // Obter informações do locale
    const { locale, availableLocales } = useLocale();
    
    // Manipular mudança de locale
    const changeLocale = (event: Event) => {
      plugins: [intlayerProxy(), // should be placed first
     svelte(), intlayer()],
    });
    

11. 8

    Alterar a URL quando o idioma mudar

    Opcional

    Para permitir que os usuários mudem de idioma e atualizem a URL de acordo, você pode criar um componente LocaleSwitcher. Este componente usará getLocalizedUrl do intlayer e push do svelte-spa-router.

    src/lib/LocaleSwitcher.svelte

    Copiar conteúdo

    Copiar código

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

    <script lang="ts">
    import { getLocaleName, getLocalizedUrl } from "intlayer";
    import { useLocale } from "svelte-intlayer";
    import { push } from "svelte-spa-router";
    
    export let currentLocale: string | undefined = undefined;
    
    // Obter informações do idioma
    const { locale, availableLocales } = useLocale();
    
    // Lidar com a mudança de idioma
    const changeLocale = (event: Event) => {
      const target = event.target as HTMLSelectElement;
      const newLocale = target.value;
      const currentUrl = window.location.pathname;
      const url = getLocalizedUrl( currentUrl, newLocale);
      push(url);
    };
    </script>
    
    <div class="locale-switcher">
      <select value={currentLocale ?? $locale} onchange={changeLocale}>
        {#each availableLocales ?? [] as loc}
          <option value={loc}>
            {getLocaleName(loc)}
          </option>
        {/each}
      </select>
    </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.

Configuração do Git

É recomendado ignorar os arquivos gerados pelo Intlayer. Isso permite que você evite fazer commit deles no seu repositório Git.

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

# Ignorar 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 Intlayer VS Code oficial.

Instalar 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 VS Code.

Ir Além

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