Guia de migração

Alfa

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

Este guia explica como migrar do anterior pacote Compiler lingo.dev para o atual pacote @lingo.dev/compiler. O novo pacote traz um nome npm com scope, uma API simplificada, integração com Vite através de plugin e um novo diretório .lingo/ para metadados.

Resumo das alterações#

Á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	Sem props
Diretório de metadados	`lingo/`	`.lingo/`
Diretiva opt-in	`'use i18n'` obrigatória	Opcional (por predefinição: traduz tudo)
Imports	`from "lingo.dev/react"`	`from "@lingo.dev/compiler/react"`

Migração passo a passo#

Substituir o pacote

Remova o pacote antigo e instale o novo:

bash

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

Atualizar imports

Substitua todos os caminhos de importação:

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

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

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

A configuração do Next.js tem agora de 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á com que a build falhe. Consulte Integração com Next.js para mais detalhes.

Atualizar 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
  ],
});

Simplificar o LingoProvider

A prop loadDictionary deixou de ser necessária. O compilador trata automaticamente do carregamento do dicionário:

tsx

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

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

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

<LingoProvider>
  <App />
</LingoProvider>

Mover o diretório de metadados

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

bash

mv lingo/ .lingo/

Atualize o seu .gitignore se fizer referência ao nome antigo do diretório. O diretório .lingo/ deve ser incluído no controlo de versões.

Atualizar diretivas 'use i18n' (opcional)

No novo pacote, 'use i18n' é opcional. Por predefinição, todos os ficheiros em sourceRoot são traduzidos. Se quiser manter o comportamento opt-in, defina useDirective: true na sua configuração:

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

Se remover useDirective (ou o definir como false), também pode remover as diretivas 'use i18n' dos seus ficheiros — todos os ficheiros em sourceRoot serão traduzidos automaticamente.

Recompilar e verificar

Inicie o servidor de desenvolvimento e confirme que as traduções aparecem:

bash

npm run dev

Confirme que:

O pseudotradutor produz marcadores [!!! ... !!!] (se estiver ativado)
Todas as strings anteriormente traduzidas continuam a funcionar
O ficheiro .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 de migração específicos do Next.js

Vite + React

Detalhes de migração específicos do Vite

Esta página foi útil?

Guia de migração

Alfa

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

Resumo das alterações#

Á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	Sem props
Diretório de metadados	`lingo/`	`.lingo/`
Diretiva opt-in	`'use i18n'` obrigatória	Opcional (por predefinição: traduz tudo)
Imports	`from "lingo.dev/react"`	`from "@lingo.dev/compiler/react"`

Migração passo a passo#

Substituir o pacote

Remova o pacote antigo e instale o novo:

bash

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

Atualizar imports

Substitua todos os caminhos de importação:

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

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

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

A configuração do Next.js tem agora de 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á com que a build falhe. Consulte Integração com Next.js para mais detalhes.

Atualizar 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
  ],
});

Simplificar o LingoProvider

A prop loadDictionary deixou de ser necessária. O compilador trata automaticamente do carregamento do dicionário:

tsx

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

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

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

<LingoProvider>
  <App />
</LingoProvider>

Mover o diretório de metadados

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

bash

mv lingo/ .lingo/

Atualize o seu .gitignore se fizer referência ao nome antigo do diretório. O diretório .lingo/ deve ser incluído no controlo de versões.

Atualizar diretivas 'use i18n' (opcional)

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

Se remover useDirective (ou o definir como false), também pode remover as diretivas 'use i18n' dos seus ficheiros — todos os ficheiros em sourceRoot serão traduzidos automaticamente.