Project Structure

The Lingo.dev Compiler creates and maintains a .lingo/ directory in your project root that stores translation metadata and cache. Understanding this directory structure helps you manage translations in version control, debug missing translations, and optimize build performance.

The .lingo/ directory#

The compiler creates this directory automatically on the first build. It contains all translation metadata used by the build pipeline:

.lingo/
  metadata.json              # Translation cache and content hashes
  locale-resolver.server.ts  # Optional: custom server-side locale resolver
  locale-resolver.client.ts  # Optional: custom client-side locale resolver

metadata.json#

This is the primary file in the .lingo/ directory. It stores:

• Content hashes - Stable hash-based identifiers for each translatable string
• Cached translations - Generated translations for each locale pair
• Source text snapshots - The source text at the time of translation, used to detect changes

The compiler reads this file at the start of each build. Strings with matching hashes reuse cached translations. Strings with changed or missing hashes are sent to the configured translation provider.

.gitignore considerations#

Do not add .lingo/ to .gitignore. The directory should be tracked in version control. A typical .gitignore for a project using the compiler:

# Do NOT ignore .lingo/ - it contains translation cache
node_modules/
dist/
.env

sourceRoot#

The sourceRoot option determines which directory the compiler scans for translatable React components:

{
  sourceRoot: "./app",  // Next.js App Router
  // or
  sourceRoot: "src",    // Vite + React
}

The compiler recursively scans all .tsx, .ts, .jsx, and .js files within sourceRoot for translatable JSX content. Files outside this directory are not processed.

Opt-in mode with 'use i18n'#

By default, the compiler translates all JSX text in sourceRoot. To switch to opt-in mode, set useDirective: true:

{
  useDirective: true,
}

In opt-in mode, only files that start with the 'use i18n' directive are processed:

'use i18n';

export function Welcome() {
  return <h1>Welcome to our app</h1>;
  // This text IS translated
}

Files without the directive are skipped:

export function InternalAdmin() {
  return <h1>Admin Dashboard</h1>;
  // This text is NOT translated
}

When to use opt-in mode#

lingoDir#

The lingoDir option changes the location of the metadata directory:

{
  lingoDir: ".lingo",  // Default
  // or
  lingoDir: ".translations",  // Custom location
}

This is useful if .lingo/ conflicts with an existing directory in your project.

Next Steps#