@intlayer/docs 7.1.8 → 7.2.0

package/docs/pt/intlayer_with_vite+svelte.md

@@ -1,7 +1,7 @@
 ---
 createdAt: 2025-04-18
-updatedAt: 2025-06-29
-title: Como traduzir seu Vite and Svelte – guia i18n 2025
+updatedAt: 2025-11-19
+title: Como traduzir sua aplicação Vite e Svelte – guia i18n 2025
 description: Descubra como tornar seu site Vite e Svelte multilíngue. Siga a documentação para internacionalizar (i18n) e traduzir.
 keywords:
   - Internacionalização
@@ -14,34 +14,47 @@ slugs:
   - doc
   - environment
   - vite-and-svelte
-# applicationTemplate: https://github.com/aymericzip/intlayer-vite-solid-template
+applicationTemplate: https://github.com/aymericzip/intlayer-vite-svelte-template
 history:
+  - version: 5.5.11
+    date: 2025-11-19
+    changes: Atualização da documentação
   - version: 5.5.10
     date: 2025-06-29
-    changes: Histórico inicial
+    changes: Histórico iniciado
 ---
 
-# Traduza seu Vite and Svelte com Intlayer | Internacionalização (i18n)
+# Traduza seu site Vite e Svelte usando Intlayer | Internacionalização (i18n)
 
-> Este pacote está em desenvolvimento. Veja a [issue](https://github.com/aymericzip/intlayer/issues/114) para mais informações. Demonstre seu interesse pelo Intlayer para Svelte curtindo a issue
+## Índice
 
-<!-- Veja o [Modelo de Aplicação](https://github.com/aymericzip/intlayer-solid-template) no GitHub. -->
+<TOC/>
 
 ## O que é o Intlayer?
 
-**Intlayer** é uma biblioteca inovadora e de código aberto para internacionalização (i18n) projetada para simplificar o suporte multilíngue em aplicações web modernas.
+**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.
-- **Beneficie de recursos avançados**, como detecção dinâmica de localidade e troca de idioma.
+- **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
 
+<iframe
+  src="https://stackblitz.com/github/aymericzip/intlayer-vite-react-template?embed=1&ctl=1&file=intlayer.config.ts"
+  className="m-auto overflow-hidden rounded-lg border-0 max-md:size-full max-md:h-[700px] md:aspect-16/9 md:w-full"
+  title="Demo CodeSandbox - Como Internacionalizar sua aplicação usando Intlayer"
+  sandbox="allow-forms allow-modals allow-popups allow-presentation allow-same-origin allow-scripts"
+  loading="lazy"
+/>
+
+Veja o [Template da Aplicação](https://github.com/aymericzip/intlayer-vite-svelte-template) no GitHub.
+
 ### Passo 1: Instalar Dependências
 
 Instale os pacotes necessários usando npm:
@@ -61,23 +74,26 @@ yarn add intlayer svelte-intlayer
 yarn add vite-intlayer --save-dev
 ```
 
-- **intlayer**
+```bash packageManager="bun"
+bun add intlayer svelte-intlayer
+bun add 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](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/dictionary/get_started.md), transpiração e [comandos CLI](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/intlayer_cli.md).
+  O pacote principal que fornece ferramentas de internacionalização para gerenciamento de configuração, tradução, [declaração de conteúdo](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/dictionary/content_file.md), transpiração e [comandos CLI](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/intlayer_cli.md).
 
 - **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 [empacotador Vite](https://vite.dev/guide/why.html#why-bundle-for-production), bem como middleware para detectar a localidade preferida do usuário, gerenciar cookies e lidar com redirecionamento de URL.
+  Inclui o plugin Vite para integrar o Intlayer com o [bundler Vite](https://vite.dev/guide/why.html#why-bundle-for-production), 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:
 
-```typescript fileName="intlayer.config.ts" codeFormat="typescript"
+```typescript fileName="intlayer.config.ts"
 import { Locales, type IntlayerConfig } from "intlayer";
 
 const config: IntlayerConfig = {
@@ -86,26 +102,7 @@ const config: IntlayerConfig = {
       Locales.ENGLISH,
       Locales.FRENCH,
       Locales.SPANISH,
-      // Seus outros idiomas
-    ],
-    defaultLocale: Locales.ENGLISH,
-  },
-};
-
-export default config;
-```
-
-```javascript fileName="intlayer.config.mjs" codeFormat="esm"
-import { Locales } from "intlayer";
-
-/** @type {import('intlayer').IntlayerConfig} */
-const config = {
-  internationalization: {
-    locales: [
-      Locales.ENGLISH,
-      Locales.FRENCH,
-      Locales.SPANISH,
-      // Seus outros idiomas
+      // Seus outros locales
     ],
     defaultLocale: Locales.ENGLISH,
   },
@@ -114,32 +111,13 @@ const config = {
 export default config;
 ```
 
-```javascript fileName="intlayer.config.cjs" codeFormat="commonjs"
-const { Locales } = require("intlayer");
-
-/** @type {import('intlayer').IntlayerConfig} */
-const config = {
-  internationalization: {
-    locales: [
-      Locales.ENGLISH,
-      Locales.FRENCH,
-      Locales.SPANISH,
-      // Seus outros idiomas
-    ],
-    defaultLocale: Locales.ENGLISH,
-  },
-};
-
-module.exports = 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](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/configuration.md).
 
-### Passo 3: Integre o Intlayer na sua Configuração do Vite
+### Passo 3: Integre o Intlayer na sua Configuração Vite
 
 Adicione o plugin intlayer na sua configuração.
 
-```typescript fileName="vite.config.ts" codeFormat="typescript"
+```typescript fileName="vite.config.ts"
 import { defineConfig } from "vite";
 import { svelte } from "@sveltejs/vite-plugin-svelte";
 import { intlayer } from "vite-intlayer";
@@ -150,29 +128,7 @@ export default defineConfig({
 });
 ```
 
-```javascript fileName="vite.config.mjs" codeFormat="esm"
-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()],
-});
-```
-
-```javascript fileName="vite.config.cjs" codeFormat="commonjs"
-const { defineConfig } = require("vite");
-const react = require("@vitejs/plugin-react-swc");
-const { intlayer } = require("vite-intlayer");
-
-// https://vitejs.dev/config/
-module.exports = 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.
+> 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
 
@@ -199,6 +155,7 @@ export default appContent;
 import { t } from "intlayer";
 
 /** @type {import('intlayer').Dictionary} */
+// Declaração do conteúdo da aplicação
 const appContent = {
   key: "app",
   content: {
@@ -249,48 +206,287 @@ module.exports = 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,mjx,cjs,cjx}`).
+> 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](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/dictionary/get_started.md).
+> Para mais detalhes, consulte a [documentação de declaração de conteúdo](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/dictionary/content_file.md).
 
 ### Passo 5: Utilize o Intlayer no Seu Código
 
-[para completar]
+```svelte fileName="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><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
 
-[para completar]
+```svelte fileName="src/App.svelte"
+<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>
+```
+
+### (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](https://github.com/aymericzip/intlayer/tree/main/docs/docs/pt/dictionary/markdown.md).
+
+```svelte fileName="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`.
+
+### (Opcional) Passo 8: Configurar o editor / CMS do intlayer
+
+Para configurar o editor do intlayer, você deve seguir a [documentação do editor intlayer](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/intlayer_visual_editor.md).
+
+Para configurar o CMS do intlayer, você deve seguir a [documentação do CMS intlayer](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/intlayer_CMS.md).
 
-### (Opcional) Passo 7: Adicionar Roteamento Localizado à sua aplicação
+Em paralelo, na sua aplicação Svelte, você deve adicionar a seguinte linha em um layout, ou na raiz da sua aplicação:
 
-[para completar]
+```svelte fileName="src/layout.svelte"
+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`:
+
+```bash packageManager="npm"
+npm install svelte-spa-router
+```
+
+```bash packageManager="pnpm"
+pnpm add svelte-spa-router
+```
+
+```bash packageManager="yarn"
+yarn add svelte-spa-router
+```
+
+```bash packageManager="bun"
+bun add svelte-spa-router
+```
+
+Então, crie um arquivo `Router.svelte` para definir suas rotas:
+
+```svelte fileName="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`:
+
+```typescript fileName="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`:
+
+```svelte fileName="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`.
+
+```typescript {3,7} fileName="vite.config.ts" codeFormat="typescript"
+import { defineConfig } from "vite";
+import { svelte } from "@sveltejs/vite-plugin-svelte";
+import { intlayer, intlayerProxy } from "vite-intlayer";
+
+  plugins: [svelte(), intlayer(), intlayerProxy()],
+});
+```
+
+```javascript {3,7} fileName="vite.config.mjs" codeFormat="esm"
+import { defineConfig } from "vite";
+import { svelte } from "@sveltejs/vite-plugin-svelte";
+import { intlayer, intlayerProxy } from "vite-intlayer";
+
+// https://vitejs.dev/config/
+export default defineConfig({
+  plugins: [svelte(), intlayer(), intlayerProxy()],
+});
+```
+
+```javascript {3,7} fileName="vite.config.cjs" codeFormat="commonjs"
+const { defineConfig } = require("vite");
+const { svelte } = require("@sveltejs/vite-plugin-svelte");
+const { intlayer, intlayerProxy } = require("vite-intlayer");
+
+// https://vitejs.dev/config/
+module.exports = defineConfig({
+  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`.
+
+```svelte fileName="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 locale
+const { locale, availableLocales } = useLocale();
+
+// Manipular mudança de locale
+const changeLocale = (event: Event) => {
+  plugins: [svelte(), intlayer(), intlayerProxy()],
+});
+```
 
 ### (Opcional) Passo 8: Alterar a URL quando o idioma mudar
 
-[para completar]
+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`.
 
-### (Opcional) Passo 9: Alterar os atributos de idioma e direção do HTML
+```svelte fileName="src/lib/LocaleSwitcher.svelte"
+<script lang="ts">
+import { getLocaleName, getLocalizedUrl } from "intlayer";
+import { useLocale } from "svelte-intlayer";
+import { push } from "svelte-spa-router";
 
-[para completar]
+export let currentLocale: string | undefined = undefined;
 
-### (Opcional) Passo 10: Criar um Componente de Link Localizado
+// Obter informações do idioma
+const { locale, availableLocales } = useLocale();
 
-[para completar]
+// 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>
+```
 
 ### 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 ao seu arquivo `.gitignore`:
+Para isso, você pode adicionar as seguintes instruções no seu arquivo `.gitignore`:
 
 ```plaintext
 # Ignorar os arquivos gerados pelo Intlayer
 .intlayer
 ```
 
-### Extensão VS Code
+### Extensão para VS Code
 
-Para melhorar sua experiência de desenvolvimento com o Intlayer, você pode instalar a **Extensão oficial do Intlayer 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](https://marketplace.visualstudio.com/items?itemName=intlayer.intlayer-vs-code-extension)
 
@@ -298,15 +494,13 @@ 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.
+- **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 Extensão Intlayer para VS Code](https://intlayer.org/doc/vs-code-extension).
+Para mais detalhes sobre como usar a extensão, consulte a [documentação da Intlayer VS Code Extension](https://intlayer.org/doc/vs-code-extension).
 
 ---
 
 ### Ir Além
 
-Para ir além, você pode implementar o [editor visual](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/intlayer_visual_editor.md) ou externalizar seu conteúdo usando o [CMS](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/intlayer_CMS.md).
-
----
+Para ir mais longe, você pode implementar o [editor visual](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/intlayer_visual_editor.md) ou externalizar seu conteúdo usando o [CMS](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/intlayer_CMS.md).