Autor:
    Criação:2025-04-18Última atualização:2026-05-31

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

    ide.intlayer.org

    Í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:

    O Intlayer é otimizado para funcionar perfeitamente com o Svelte, oferecendo escopo de conteúdo em nível de componente, traduções reativas e todos os recursos necessários para dimensionar a internacionalização (i18n).

    Em vez de carregar arquivos JSON enormes em suas páginas, carregue apenas o conteúdo necessário. O Intlayer ajuda a reduzir o tamanho do bundle e das páginas em até 50%.

    Definir o escopo do conteúdo do seu aplicativo facilita a manutenção de aplicativos de grande escala. Você pode duplicar ou excluir uma única pasta de recursos sem o fardo mental de revisar toda a base de código de seu conteúdo. Além disso, o Intlayer é totalmente tipado (fully typed) para garantir a precisão do seu conteúdo.

    A co-localização de conteúdo reduz o contexto necessário pelos Large Language Models (LLMs). O Intlayer também vem com um conjunto de ferramentas, como uma CLI para testar traduções ausentes,LSP, MCP, e habilidades do agente, para tornar a experiência do desenvolvedor (DX) ainda mais tranquila para os agentes de IA.

    Use a automação para traduzir seu pipeline de CI/CD usando o LLM de sua escolha às custas de seu provedor de IA. O Intlayer também oferece um compilador para automatizar a extração de conteúdo, bem como uma plataforma web para ajudar a traduzir em segundo plano.

    Conectar arquivos JSON enormes a componentes pode levar a problemas de desempenho e reatividade. O Intlayer otimiza o carregamento do seu conteúdo no momento da construção.

    Mais do que apenas uma solução i18n, o Intlayer fornece um [editor visual] auto-hospedado(/pt/doc/concept/editor) e um CMS completo para ajudá-lo a gerenciar seu conteúdo multilíngue em tempo real, facilitando a colaboração com tradutores, redatores e outros membros da equipe. O conteúdo pode ser armazenado local e/ou remotamente.

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

    ide.intlayer.org

    Veja o Template da Aplicação no GitHub.

    1. Instalar Dependências

      Instale os pacotes necessários usando npm:

      bash
      npx intlayer@canary init --interactive    # v9# npx intlayer init                       # v8
      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
      npm install intlayer svelte-intlayernpm 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. Configuração do seu projeto

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

      intlayer.config.ts
      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. Integre o Intlayer na sua Configuração Vite

      Adicione o plugin intlayer na sua configuração.

      vite.config.ts
      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. Declare Seu Conteúdo

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

      src/app.content.tsx
      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. Utilize o Intlayer no Seu Código

      src/App.svelte
      <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.

    6. Alterar o idioma do seu conteúdo

      Opcional
      src/App.svelte
      <script lang="ts">import  { getLocaleName } from 'intlayer';import { useLocale } from "svelte-intlayer";// Obter informações do locale e função setLocaleconst { locale, availableLocales, setLocale } = useLocale();// Manipular mudança de localeconst 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. 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
      <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. 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. 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
      npm install svelte-spa-routernpx intlayer init

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

      src/Router.svelte
      <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
      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
      <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.
      vite.config.ts
      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. 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
      <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 localeconst { locale, availableLocales } = useLocale();// Manipular mudança de localeconst changeLocale = (event: Event) => {  plugins: [intlayerProxy(), // should be placed first svelte(), intlayer()],});

    11. 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
      <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 idiomaconst { locale, availableLocales } = useLocale();// Lidar com a mudança de idiomaconst 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. 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
      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;

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

      bash
      npx intlayer extract

    (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

    generate-seo.mjs
    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

    package.json
    {  "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:

    bash
    # 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.

    Vite e Solid
    SvelteKit