Configuration

Languine uses a JSON configuration file (languine.json) to manage your translation setup. This file defines your source and target languages, as well as the files that need to be translated.


Basic Configuration

Here's a basic example in both formats:

languine.json
{
  "locale": {
    "source": "en",
    "targets": ["es", "fr", "de"]
  },
  "files": {
    "json": {
      "include": ["locales/[locale].json"]
    }
  }
}

Let's break down the different sections in the configuration file.


Locale Configuration

The locale section defines your translation languages:

  • source: Your primary language for content creation (e.g., "en" for English)
  • targets: An array of languages you want to translate into (e.g., ["es", "fr", "de"] for Spanish, French, and German)

Languine supports a wide range of language codes, including:

  • Simple codes: en, es, fr, de
  • Region-specific codes: pt-BR, zh-CN, zh-TW

File Configuration

The files section defines which files Languine should translate. You can configure multiple file types and patterns:


JSON Files

typescript
files: {
  json: {
    include: ["locales/[locale].json"],
  },
}

Markdown/MDX Files

typescript
files: {
  md: {
    include: ["docs/[locale]/*.md"],
  },
  mdx: {
    include: ["blog/[locale]/*.mdx"],
  },
}

Mobile Platform Files

For iOS (Xcode):

typescript
files: {
  "xcode-xcstrings": {
    include: ["Example/Localizable.xcstrings"],
  },
  // Or for traditional .strings files
  "xcode-strings": {
    include: ["Example/[locale].lproj/Localizable.strings"],
  },
}

For Android:

typescript
files: {
  android: {
    include: ["locales/[locale].xml"],
  },
}

Other Formats

Here's a complete list of file formats supported by Languine:

  • JSON - Standard JSON translation files
  • YAML - YAML translation files
  • Properties - Java properties files
  • Android - Android XML resource files
  • iOS - iOS localization files
  • iOS Stringsdict - iOS pluralization files
  • iOS XCStrings - Modern Xcode string catalogs
  • Markdown - Documentation files
  • MDX - Documentation with JSX
  • HTML - HTML files
  • JavaScript - JavaScript files
  • TypeScript - TypeScript files
  • Gettext PO - GetText translation files
  • XLIFF - XML Localization Interchange File Format
  • CSV - Spreadsheet-based translations
  • XML - XML resource files
  • Flutter ARB - Application Resource Bundle files
  • PHP - PHP translation files

File Patterns

The [locale] placeholder in file patterns is automatically replaced with the appropriate language code during translation. For example:

  • locales/[locale].json becomes:
    • locales/en.json
    • locales/es.json
    • locales/fr.json

You can include multiple patterns for each file type and use glob patterns:

typescript
files: {
  json: {
    include: [
      "src/locales/[locale].json",
      "src/components/[locale]/*.json"
    ],
  },
}

Project ID (Optional)

If you're using Languine's cloud services, you can include your project ID in the configuration:

typescript
{
  "projectId": "prj_your_project_id",
  "locale": {
    // ... locale config
  },
  files: {
    // ... files config
  },
}

Translation State Tracking

Languine automatically creates and maintains a languine.lock file to track the state of your translations. This file:

  • Tracks which content has been translated
  • Helps identify what needs to be updated when source content changes
  • Should be committed to your version control system

You don't need to manually edit the lock file - Languine manages it automatically when you run translation commands.

Best Practices

  1. Version Control: Always commit both languine.json and languine.lock to your repository
  2. File Organization: Keep your translation files organized in a consistent directory structure
  3. Language Codes: Use standard language codes to ensure compatibility
  4. Patterns: Use specific include patterns to avoid translating unnecessary files
  5. Project ID: Keep your project ID secure and don't share it publicly if you're using cloud services, use the LANGUINE_PROJECT_ID environment variable instead.