Configuration

Babely uses a JSON configuration file (babely.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:

babely.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)

Babely 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 Babely 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 Babely:

  • โ—‡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 Babely'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

Babely automatically creates and maintains a babely.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 - Babely manages it automatically when you run translation commands.

Best Practices

  1. โ—‡Version Control: Always commit both babely.json and babely.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 BABELY_PROJECT_ID environment variable instead.
์ธ์ฆCLI