Traduza seu Vite and Solid com Intlayer | Internacionalização (i18n)

VideoCodeDemo

www.youtube.com

Open embedded page in fullscreen

ide.intlayer.org

Open embedded page in fullscreen

intlayer-vite-solid.vercel.app

Open embedded page in fullscreen

Table of Contents

Por que Intlayer em vez de alternativas?

Comparado com soluções principais como @solid-primitives/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 Solid

Table of Contents

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

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

   • vite-intlayer Inclui o plugin Vite para integrar o Intlayer com o empacotador Vite, assim 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

   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;
   

   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 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 react from "@vitejs/plugin-react-swc";
   import { intlayer } from "vite-intlayer";
   
   // https://vitejs.dev/config/
   export default defineConfig({
     plugins: [react(), 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";
   
   const appContent = {
     key: "app",
     content: {},
   } satisfies Dictionary;
   
   export default appContent;
   

   As 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 ficheiro de declaração de conteúdo (por padrão, .content.{json,ts,tsx,js,jsx,mjs,cjs,md,mdx,yaml,yml}).

5. 5

   Utilize o Intlayer no Seu Código

   Aceda aos 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 { createSignal, type Component } from "solid-js";
   import solidLogo from "./assets/solid.svg";
   import viteLogo from "/vite.svg";
   import "./App.css";
   import { IntlayerProvider, useIntlayer } from "solid-intlayer";
   
   const AppContent: Component = () => {
     const [count, setCount] = createSignal(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://www.solidjs.com/" target="_blank">
             <img
               src={solidLogo}
               class="logo solid"
               alt={content.solidLogo.value}
             />
           </a>
         </div>
         <h1>{content.title}</h1>
         <div class="card">
           <button onClick={() => setCount((count) => count + 1)}>
             {content.count({ count: count() })}
           </button>
           <p>{content.edit}</p>
         </div>
         <p class="read-the-docs">{content.readTheDocs}</p>
       </>
     );
   };
   
   const App: Component = () => (
     <IntlayerProvider>
       <AppContent />
     </IntlayerProvider>
   );
   
   export default App;
   

   No Solid, useIntlayer retorna uma função accessor (por exemplo, `content.). Deve chamar esta função para aceder ao conteúdo reativo.

   Se quiser usar o seu conteúdo num atributo string, como alt, title, href, aria-label, etc., 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)}" />
   

6. 6

   Alterar o idioma do seu conteúdo

   Opcional

   Para alterar o idioma do seu conteúdo, pode usar a função setLocale fornecida pelo hook useLocale. Esta função permite definir a locale da aplicação e atualizar o conteúdo em conformidade.

   src/components/LocaleSwitcher.tsx

   Copiar conteúdo

   Copiar código

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

   import { type Component, For } from "solid-js";
   import { Locales } from "intlayer";
   import { useLocale } from "solid-intlayer";
   
   const LocaleSwitcher: Component = () => {
     const { locale, setLocale, availableLocales } = useLocale();
   
     return (
       <select
         value={locale()}
         onChange={(e) => setLocale(e.currentTarget.value as Locales)}
       >
         <For each={availableLocales}>
           {(loc) => (
             <option value={loc} selected={loc === locale()}>
               {loc}
             </option>
           )}
         </For>
       </select>
     );
   };
   

7. 7

   Adicionar Roteamento localizado à sua aplicação

   Opcional

   O objetivo deste passo é criar rotas únicas para cada idioma. Isto é ú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
   

   Para adicionar roteamento por localeizado à sua aplicação, pode usar @solidjs/router.

   Primeiro, instale as dependências necessárias:

   bash

   Copiar conteúdo

   Copiar código

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

   npm install @solidjs/router
   

   Depois, envolva a sua aplicação com o Router e defina as suas rotas usando localeMap:

   src/index.tsx

   Copiar conteúdo

   Copiar código

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

   import { render } from "solid-js/web";
   import { Router } from "@solidjs/router";
   import App from "./App";
   
   const root = document.getElementById("root");
   
   render(
     () => (
       <Router>
         <App />
       </Router>
     ),
     root!
   );
   

   src/App.tsx

   Copiar conteúdo

   Copiar código

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

   import { type Component } from "solid-js";
   import { Route } from "@solidjs/router";
   import { localeMap } from "intlayer";
   import { IntlayerProvider } from "solid-intlayer";
   import Home from "./pages/Home";
   import About from "./pages/About";
   
   const App: Component = () => (
     <IntlayerProvider>
       {localeMap(({ locale, urlPrefix }) => (
         <Route
           path={urlPrefix || "/"}
           component={(props: any) => (
             <IntlayerProvider locale={locale}>{props.children}</IntlayerProvider>
           )}
         >
           <Route path="/" component={Home} />
           <Route path="/about" component={About} />
         </Route>
       ))}
     </IntlayerProvider>
   );
   
   export default App;
   

8. 8

   Alterar a URL quando o idioma mudar

   Opcional

   Para alterar a URL quando a locale mudar, pode usar a prop onLocaleChange fornecida pelo hook useLocale. Pode usar os hooks useNavigate e useLocation de @solidjs/router 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 { type Component, For } from "solid-js";
   import { useLocation, useNavigate } from "@solidjs/router";
   import { getLocalizedUrl } from "intlayer";
   import { useLocale } from "solid-intlayer";
   
   const LocaleSwitcher: Component = () => {
     const location = useLocation();
     const navigate = useNavigate();
     const { locale, setLocale, availableLocales } = useLocale({
       onLocaleChange: (loc) => {
         const pathWithLocale = getLocalizedUrl(location.pathname, loc);
         navigate(pathWithLocale);
       },
     });
   
     return (
       <select
         value={locale()}
         onChange={(e) => setLocale(e.currentTarget.value as any)}
       >
         <For each={availableLocales}>
           {(loc) => (
             <option value={loc} selected={loc === locale()}>
               {loc}
             </option>
           )}
         </For>
       </select>
     );
   };
   

9. 9

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

   Opcional

   Atualize os atributos lang e dir da tag <html> para corresponder à locale atual para acessibilidade e SEO.

   src/App.tsx

   Copiar conteúdo

   Copiar código

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

   import { createEffect, type Component } from "solid-js";
   import { useLocale } from "solid-intlayer";
   import { getHTMLTextDir } from "intlayer";
   
   const AppContent: Component = () => {
     const { locale } = useLocale();
   
     createEffect(() => {
       document.documentElement.lang = locale();
       document.documentElement.dir = getHTMLTextDir(locale());
     });
   
     return (
       // ... O conteúdo da sua aplicação
     );
   };
   

10. 10

    Criar um Componente de Link Localizado

    Opcional

Crie um componente Link personalizado que prefixa automaticamente os URLs internos com o idioma atual.

src/components/Link.tsx

Copiar conteúdo

Copiar código

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

import { type ParentComponent } from "solid-js";
import { A, type AnchorProps } from "@solidjs/router";
import { getLocalizedUrl } from "intlayer";
import { useLocale } from "solid-intlayer";

export const Link: ParentComponent<AnchorProps> = (props) => {
  const { locale } = useLocale();

  const isExternal = () => props.href.startsWith("http");
  const localizedHref = () =>
    isExternal() ? props.href : getLocalizedUrl(props.href, locale());

  return <A {...props} href={localizedHref()} />;
};

11. 11

    Renderizar Markdown

    Opcional

    O Intlayer suporta a renderização de conteúdo Markdown diretamente na sua aplicação Solid usando o seu próprio parser interno. Por padrão, o Markdown é tratado como texto simples. Para renderizá-lo como HTML rico, envolva a sua aplicação com o MarkdownProvider.

    Depois pode usá-lo nos seus componentes:

    tsx

    Copiar conteúdo

    Copiar código

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

    import { useIntlayer } from "solid-intlayer";
    
    const MyComponent = () => {
      const content = useIntlayer("my-content");
    
      return (
        <div>
          {/* Renderizado como HTML via MarkdownProvider */}
          {content.markdownContent}
        </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

Certifique-se de que a sua configuração TypeScript inclui os tipos autogerados.

{
  "compilerOptions": {
    // ...
  },
  "include": ["src", ".intlayer/**/*.ts"],
}

Configuração do Git

É recomendado ignorar os ficheiros gerados pelo Intlayer. Isto permite evitar que sejam cometidos no seu repositório Git.

Para isso, pode adicionar as seguintes instruções ao seu ficheiro .gitignore:

#  Ignorar os ficheiros gerados pelo Intlayer
.intlayer

Extensão para VS Code

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

Instalar a partir do VS Code Marketplace

Ir Mais Longe

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