Guia de migração

Alpha

O Compiler da Lingo.dev está em alpha. Ele é instável, não é recomendado para uso em produção e as APIs podem mudar entre versões.

Este guia mostra como migrar do pacote anterior do Compiler lingo.dev para o pacote atual @lingo.dev/compiler. O novo pacote traz um nome npm com escopo, API simplificada, integração com Vite baseada em plugin e um novo diretório .lingo/ para metadados.

Resumo das mudanças#

Área	Antes (`lingo.dev`)	Depois (`@lingo.dev/compiler`)
Nome do pacote	`lingo.dev`	`@lingo.dev/compiler`
Integração com Next.js	Alteração direta da configuração	Wrapper assíncrono `withLingo()`
Integração com Vite	Configuração manual	`lingoCompilerPlugin`
LingoProvider	Prop `loadDictionary` obrigatória	Nenhuma prop necessária
Diretório de metadados	`lingo/`	`.lingo/`
Diretiva de ativação	`'use i18n'` obrigatória	Opcional (padrão: traduzir tudo)
Imports	`from "lingo.dev/react"`	`from "@lingo.dev/compiler/react"`

Migração passo a passo#

Substitua o pacote

Remova o pacote antigo e instale o novo:

bash

npm uninstall lingo.dev
npm install @lingo.dev/compiler

Atualize os imports

Substitua todos os caminhos de import:

// Before
import { LingoProvider, useLingoContext } from "lingo.dev/react";

// After
import { LingoProvider, useLingoContext } from "@lingo.dev/compiler/react";

Atualize a configuração do Next.js (se aplicável)

A configuração do Next.js agora precisa ser uma função assíncrona:

// Before
import { withLingo } from "lingo.dev/next";
const nextConfig = {};
export default withLingo(nextConfig, { /* options */ });

// After
import type { NextConfig } from "next";
import { withLingo } from "@lingo.dev/compiler/next";

const nextConfig: NextConfig = {};

export default async function (): Promise<NextConfig> {
  return await withLingo(nextConfig, {
    sourceRoot: "./app",
    sourceLocale: "en",
    targetLocales: ["es", "de", "fr"],
    models: "lingo.dev",
  });
}

O wrapper de função assíncrona é obrigatório. Uma exportação síncrona fará o build falhar. Consulte Integração com Next.js para mais detalhes.

Atualize a configuração do Vite (se aplicável)

Substitua qualquer configuração manual por lingoCompilerPlugin:

// vite.config.ts
import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
import { lingoCompilerPlugin } from "@lingo.dev/compiler/vite";

export default defineConfig({
  plugins: [
    lingoCompilerPlugin({
      sourceRoot: "src",
      sourceLocale: "en",
      targetLocales: ["es", "de", "fr"],
      models: "lingo.dev",
    }),
    react(), // Must come AFTER lingoCompilerPlugin
  ],
});

Simplifique o LingoProvider

A prop loadDictionary não é mais necessária. O Compiler cuida do carregamento do dicionário automaticamente:

tsx

// Before
import { LingoProvider } from "lingo.dev/react";

<LingoProvider loadDictionary={loadDictionary}>
  <App />
</LingoProvider>

// After
import { LingoProvider } from "@lingo.dev/compiler/react";

<LingoProvider>
  <App />
</LingoProvider>

Mova o diretório de metadados

Renomeie o diretório de metadados de lingo/ para .lingo/:

bash

mv lingo/ .lingo/

Atualize seu .gitignore se ele fizer referência ao nome antigo do diretório. O diretório .lingo/ deve ser commitado no controle de versão.

Atualize as diretivas 'use i18n' (opcional)

No novo pacote, 'use i18n' é opcional. Por padrão, todos os arquivos em sourceRoot são traduzidos. Se você quiser manter o comportamento de ativação manual, defina useDirective: true na sua configuração:

{
  useDirective: true, // Keep requiring 'use i18n' in each file
}

Se você remover useDirective (ou defini-lo como false), também poderá remover as diretivas 'use i18n' dos seus arquivos — todos os arquivos em sourceRoot serão traduzidos automaticamente.

Recompile e verifique

Execute o servidor de desenvolvimento e confirme se as traduções aparecem:

bash

npm run dev

Verifique se:

O pseudotradutor gera marcadores [!!! ... !!!] (se estiver ativado)
Todas as strings traduzidas anteriormente continuam funcionando
O arquivo .lingo/metadata.json é criado ou atualizado

Próximos passos#

Configuração

Guia completo de configuração

Referência de configuração

Todas as novas opções de configuração

Integração com Next.js

Detalhes da migração específicos do Next.js

Vite + React

Detalhes da migração específicos do Vite

Esta página foi útil?

Guia de migração

Alpha

O Compiler da Lingo.dev está em alpha. Ele é instável, não é recomendado para uso em produção e as APIs podem mudar entre versões.

Resumo das mudanças#

Área	Antes (`lingo.dev`)	Depois (`@lingo.dev/compiler`)
Nome do pacote	`lingo.dev`	`@lingo.dev/compiler`
Integração com Next.js	Alteração direta da configuração	Wrapper assíncrono `withLingo()`
Integração com Vite	Configuração manual	`lingoCompilerPlugin`
LingoProvider	Prop `loadDictionary` obrigatória	Nenhuma prop necessária
Diretório de metadados	`lingo/`	`.lingo/`
Diretiva de ativação	`'use i18n'` obrigatória	Opcional (padrão: traduzir tudo)
Imports	`from "lingo.dev/react"`	`from "@lingo.dev/compiler/react"`

Migração passo a passo#

Substitua o pacote

Remova o pacote antigo e instale o novo:

bash

npm uninstall lingo.dev
npm install @lingo.dev/compiler

Atualize os imports

Substitua todos os caminhos de import:

// Before
import { LingoProvider, useLingoContext } from "lingo.dev/react";

// After
import { LingoProvider, useLingoContext } from "@lingo.dev/compiler/react";

Atualize a configuração do Next.js (se aplicável)

A configuração do Next.js agora precisa ser uma função assíncrona:

// Before
import { withLingo } from "lingo.dev/next";
const nextConfig = {};
export default withLingo(nextConfig, { /* options */ });

// After
import type { NextConfig } from "next";
import { withLingo } from "@lingo.dev/compiler/next";

const nextConfig: NextConfig = {};

export default async function (): Promise<NextConfig> {
  return await withLingo(nextConfig, {
    sourceRoot: "./app",
    sourceLocale: "en",
    targetLocales: ["es", "de", "fr"],
    models: "lingo.dev",
  });
}

O wrapper de função assíncrona é obrigatório. Uma exportação síncrona fará o build falhar. Consulte Integração com Next.js para mais detalhes.

Atualize a configuração do Vite (se aplicável)

Substitua qualquer configuração manual por lingoCompilerPlugin:

// vite.config.ts
import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
import { lingoCompilerPlugin } from "@lingo.dev/compiler/vite";

export default defineConfig({
  plugins: [
    lingoCompilerPlugin({
      sourceRoot: "src",
      sourceLocale: "en",
      targetLocales: ["es", "de", "fr"],
      models: "lingo.dev",
    }),
    react(), // Must come AFTER lingoCompilerPlugin
  ],
});

Simplifique o LingoProvider

A prop loadDictionary não é mais necessária. O Compiler cuida do carregamento do dicionário automaticamente:

tsx

// Before
import { LingoProvider } from "lingo.dev/react";

<LingoProvider loadDictionary={loadDictionary}>
  <App />
</LingoProvider>

// After
import { LingoProvider } from "@lingo.dev/compiler/react";

<LingoProvider>
  <App />
</LingoProvider>

Mova o diretório de metadados

Renomeie o diretório de metadados de lingo/ para .lingo/:

bash

mv lingo/ .lingo/

Atualize seu .gitignore se ele fizer referência ao nome antigo do diretório. O diretório .lingo/ deve ser commitado no controle de versão.

Atualize as diretivas 'use i18n' (opcional)

{
  useDirective: true, // Keep requiring 'use i18n' in each file
}

Recompile e verifique

Execute o servidor de desenvolvimento e confirme se as traduções aparecem:

bash

npm run dev

Verifique se:

O pseudotradutor gera marcadores [!!! ... !!!] (se estiver ativado)
Todas as strings traduzidas anteriormente continuam funcionando
O arquivo .lingo/metadata.json é criado ou atualizado

Próximos passos#

Configuração

Guia completo de configuração

Referência de configuração

Todas as novas opções de configuração

Integração com Next.js

Detalhes da migração específicos do Next.js

Vite + React

Detalhes da migração específicos do Vite

Esta página foi útil?