Skip to content

Translate TypeScript Localization Files with Default Exports

Simplify your TypeScript project localization with Lingo.dev's TypeScript file translation capabilities - perfect for configuration files, constant modules, and other TypeScript files with string literals.

Quick Setup

Create an i18n.json configuration file in your project root:

json
{
  "version": 1,
  "locale": {
    "source": "en",
    "targets": ["es", "fr", "de"]
  },
  "buckets": {
    "typescript": {
      "include": ["config/locales/[locale].ts"]
    }
  }
}

This simple configuration:

  • Sets English as your source language
  • Targets Spanish, French, and German translations
  • Looks for TypeScript files in the config/locales folder with locale-based naming (e.g., en.ts, es.ts)

Default Export Requirement

For TypeScript translation to work properly, your file must export an object as the default export:

typescript
// This works - default export object
export default {
  greeting: "Hello, world!",
  farewell: "Goodbye!"
};
typescript
// This also works - variable with default export
const messages = {
  welcome: "Welcome to our app",
  error: "Something went wrong"
};
export default messages;

One Command Translation

Translate all your TypeScript files with a single command:

bash
npx lingo.dev@latest i18n

This automatically:

  1. Reads your source language TypeScript files
  2. Identifies new or modified content
  3. Translates only what's changed
  4. Creates or updates target language files

Smart TypeScript Handling

Nested Structures

Lingo.dev preserves complex hierarchies in your TypeScript files:

typescript
export default {
  nav: {
    home: "Home",
    about: {
      team: "Our Team",
      mission: "Our Mission"
    }
  }
};

Array Support

Arrays of strings or objects are fully supported:

typescript
export default {
  greetings: ["Hello", "Hi", "Hey"],
  categories: [
    { name: "Electronics", description: "Electronic devices" },
    { name: "Books", description: "Reading materials" }
  ]
};

Complex Nested Structures

Even deeply nested structures with mixed objects and arrays are handled properly:

typescript
export default {
  app: {
    name: "My App",
    version: "1.0.0",
    features: ["Login", "Dashboard", "Settings"],
    pages: [
      { 
        title: "Home", 
        sections: [
          { heading: "Welcome", content: "Welcome to our app" },
          { heading: "Features", content: "Check out our features" }
        ]
      },
      { 
        title: "About", 
        sections: [
          { heading: "Our Story", content: "We started in 2020" }
        ]
      }
    ]
  }
};

Non-String Value Handling

Only string values are extracted for translation, while numbers, booleans, and other non-string values remain untouched:

typescript
export default {
  greeting: "Hello, world!", // Will be translated
  count: 42,                 // Remains unchanged
  enabled: true              // Remains unchanged
};

Advanced Configuration Options

Protect Technical Content with Key Locking

Prevent translation of specific keys by using the lockedKeys option:

json
"typescript": {
  "include": ["config/locales/[locale].ts"],
  "lockedKeys": [
    "app/version",
    "settings/apiKey",
    "branding/companyName"
  ]
}

Key locking notes:

  • Use forward slash (/) as the separator for nested keys
  • Works with keys containing dots (e.g., config/api.url)
  • Compatible with nested objects and array elements

For more details, see the Key Locking documentation.

Multi-Format Projects

Configure multiple file types in a single project:

json
"buckets": {
  "typescript": {
    "include": ["config/locales/[locale].ts"]
  },
  "json": {
    "include": ["locales/[locale].json"]
  }
}

In Conclusion

With Lingo.dev, you can now localize TypeScript files with default exports. This approach supports nested objects, arrays, and preserves non-string values while translating string literals. If you have TypeScript files in your project, you can include them in your localization workflow alongside other file formats.