Svelte langsys-js-svelte

Uma camada fina do Svelte 5 sobre o langsys-js-typescript — a integração madura e canônica. Os sinais base já atendem ao contrato de stores do Svelte, então as traduções são lidas com a sintaxe de store $.

Add Langsys translation to this Svelte app.

1. Read https://docs.langsys.dev/llms.txt, then follow
   https://docs.langsys.dev/learn/sdk/svelte/ for the install and setup.
2. The English text in the code is the translation key. Wrap user-facing
   strings as they are: no keys file, no extraction step, and no
   hand-written plural or gender branches (Langsys generates those).
3. Read the Langsys project id and API key from environment variables.
   The write key is for development and servers only; anything shipped
   to the browser gets the read-only key.
4. Keep brand names and user-generated content out of translation.

Instalar

npm install langsys-js-svelte

Ainda não tem projeto ou chaves? O Início rápido entrega os dois em dois minutos.

Inicializar

import { writable } from 'svelte/store';
import { LangsysApp } from 'langsys-js-svelte';

const locale = writable('en-US'); // a standard Svelte writable

await LangsysApp.init({
  projectid: import.meta.env.VITE_LANGSYS_PROJECT_ID,
  key: import.meta.env.VITE_LANGSYS_API_KEY, // read-only in the browser
  UserLocaleStore: locale,
});

Playground interativo

Edite a frase e a categoria, defina os parâmetros como campos ou JSON bruto, depois troque o idioma e veja o SDK real traduzir ao vivo.

const value = $derived($t("Hello, {name}! You have {count} new messages.", "Greetings", {"name":"Sarah","count":3}));

<script>
  import { t } from 'langsys-js-svelte';
  let name = 'Sarah';
</script>

<p>{$t('Hello, {name}!', 'Greetings', { name })}</p>

Qual devo usar?

Regra prática: string → $t · frase com marcação → <Phrase> · trecho de marcação → <Translate> · intocável → <DontTranslate>.

Cada componente de conteúdo renderizado ao vivo à esquerda; o código que o produz à direita, com o corte da demonstração acima do par.

<script>
  import { Translate } from 'langsys-js-svelte';
</script>

<Translate category="Home">
  <h3>Welcome to our store</h3>
  <p>Browse the catalog in your language.</p>
</Translate>

<Phrase category="Cart" params={{ name: 'Sarah', count: 3 }}>
  Hi %name%, you have %count% items in your cart.
</Phrase>

<!-- Inside a translated region, the marked span alone stays verbatim. -->
<Translate category="Tour">
  <p>Welcome! <DontTranslate>This sentence always stays in English.</DontTranslate> Thanks for visiting!</p>
</Translate>

Concordância de gênero

Espanhol, francês ou russo flexionam {username} has been invited de acordo com a pessoa a quem se refere. O Langsys gera essas variantes durante a tradução — do mesmo jeito que gera os plurais — e o argumento recebe o nome da variável, com _gender no final: male, female ou other. Informe-o sempre que souber. Como funciona e como encontrar as frases que precisam dele →

<script>
  import { t } from 'langsys-js-svelte';
  export let user; // user.gender is 'male' | 'female' | 'other'
</script>

<!-- Pass the agreement argument alongside the value it inflects. -->
<p>{$t('{username} has been invited', 'Team',
    { username: user.name, username_gender: user.gender })}</p>

Não sabe o gênero? Passe 'other' explicitamente — é a variação neutra. Se ele estiver ausente mesmo assim, o SDK usa a variação other para você (langsys-js-typescript 0.6.4 e posterior), e a frase continua correta.

Blocos de conteúdo

Uma região <Translate> é registrada como um bloco de conteúdo: a seção é traduzida e revisada como uma unidade no Translation Manager, mas cada trecho de texto dentro dela continua sendo uma frase independente. Escreva a mesma frase em outro lugar e ela reaproveita a tradução que já existe.

<Translate category="Home">
    <h3>Welcome to our store</h3>
    <p>Browse the catalog in your language.</p>
    <p>Free shipping on orders over $50.</p>
</Translate>

Categorias

Outras bibliotecas de i18n obrigam você a inventar uma chave para cada string porque uma mesma palavra pode ter dois significados. Na Langsys, a frase permanece no seu código e a categoria faz esse papel: a frase mais a categoria formam a chave, então a mesma palavra em duas categorias se torna duas traduções.

<!-- The phrase plus its category is the key. -->
<a href="/">{$t('Home', 'Main menu')}</a>          <!-- es: Inicio -->
<h2>{$t('Home', 'Home repairs')}</h2>           <!-- es: Hogar -->

Atributos

Um formulário fica só meio traduzido se o texto visível muda, mas o placeholder, a descrição da imagem e o rótulo para leitores de tela continuam em inglês. <Translate> cuida deles na mesma passada: placeholder, alt, title, aria-label e aria-placeholder são traduzidos junto com o texto, sem nenhuma marcação extra. Tudo o que estiver marcado com translate="no" é ignorado, inclusive os elementos filhos.

<Translate category="Checkout">
    <label>Email address</label>
    <input placeholder="[email protected]" />
    <img src="/lock.svg" alt="Secure checkout" />
    <button aria-label="Place your order">
        Place order
    </button>
</Translate>

Números e datas

Passe números e datas como parâmetros e o SDK os formata para o idioma exibido, seguindo o CLDR (os dados de localidade do Unicode): um número passa por Intl.NumberFormat e uma Date por Intl.DateTimeFormat. Isso vai além do separador: o agrupamento é um formato, então 1234567 é 1,234,567 em inglês dos EUA e 12,34,567 em inglês da Índia (en-IN).

O outro lado da moeda: tudo que é passado como número é tratado como quantidade. Um número de pedido não é uma quantidade, então passe-o como string, ou o alemão mostrará a referência do seu pedido como 1.048.576.

<script lang="ts">
    import { t } from 'langsys-js-svelte';
    const renewsAt = new Date(2026, 2, 14); // 14 March 2026, local time
</script>

<p>{$t('Balance: {amount}', 'Billing', { amount: 1234.5 })}</p>
<p>{$t('Renews {when}', 'Billing', { when: renewsAt })}</p>

<!-- An order number is not a quantity: pass it as a string. -->
<p>{$t('Order {ref}', 'Billing', { ref: '1048576' })}</p>

Renderização no servidor

Busque o catálogo no servidor (SvelteKit) e passe-o ao cliente, para que o SDK inicie sem precisar buscá-lo de novo. O SDK traduz no navegador, então o HTML renderizado no servidor fica no idioma base até que ele seja iniciado.

// SvelteKit: +layout.server.ts seeds the catalog, the client init reuses it.
LangsysApp.init({
  projectid, key,
  UserLocaleStore: locale,
  initialTranslations,        // fetched on the server
  initialTranslationsLocale,  // fetched on the server
  ssrTokenStrategy: 'client',
});