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

Índice

O que é o Intlayer?

Intlayer é uma biblioteca inovadora e open-source de internacionalização (i18n) projetada para simplificar o suporte multilíngue em aplicações web modernas.

Com o Intlayer, você pode:

• Gerenciar traduções facilmente usando dicionários declarativos no nível do componente.
• Localizar dinamicamente metadados, rotas e conteúdo.
• Garantir suporte ao TypeScript com tipos gerados automaticamente, melhorando o autocompletar e a detecção de erros.
• Aproveitar recursos avançados, como detecção e troca dinâmica de locale.

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

Veja o Template da Aplicação no GitHub.

Passo 1: Instalar Dependências

Instale os pacotes necessários usando npm:

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.

Passo 2: Configuração do seu projeto

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

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.

Passo 3: Integre o Intlayer na sua Configuração Vite

Adicione o plugin intlayer na sua configuração.

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.

Passo 4: Declare Seu Conteúdo

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

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,mjx,cjs,cjx}).

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

Passo 5: Utilize o Intlayer no Seu Código

<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><svelte:component this={$content.title} /></h1><!-- Para renderizar o conteúdo como uma string --><div aria-label={$content.title.value}></div>

(Opcional) Passo 6: Alterar o idioma do seu conteúdo

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

(Opcional) Passo 7: Renderizar Markdown

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.

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

(Opcional) Passo 8: Configurar o editor / CMS do intlayer

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.

Em paralelo, na sua aplicação Svelte, você deve adicionar a seguinte linha em um layout, ou na raiz da sua aplicação:

import { useIntlayerEditor } from "svelte-intlayer";useIntlayerEditor();

(Opcional) Passo 7: Adicionar roteamento localizado à sua aplicação

Para lidar com roteamento localizado 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:

npm install svelte-spa-router

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

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

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:

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

import { defineConfig } from "vite";import { svelte } from "@sveltejs/vite-plugin-svelte";import { intlayer, intlayerProxy } from "vite-intlayer";  plugins: [svelte(), intlayer(), intlayerProxy()],});

(Opcional) Passo 8: Alterar a URL quando o locale mudar

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.

<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: [svelte(), intlayer(), intlayerProxy()],});

(Opcional) Passo 8: Alterar a URL quando o idioma mudar

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.

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

Configuração do Git

É recomendado ignorar os arquivos gerados pelo Intlayer. Isso permite evitar que eles sejam comitados no seu repositório Git.

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

# Ignorar os arquivos gerados pelo Intlayer.intlayer

Extensão para VS Code

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

Instalar no VS Code Marketplace

Esta extensão oferece:

• Autocompletar para chaves de tradução.
• Detecção de erros em tempo real para traduções ausentes.
• Pré-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 Intlayer VS Code Extension.

Ir Além

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