Skip to main content

Languages and Key Order

In Branchlate, effectively managing your project's languages and controlling the translation key order can significantly streamline translation management, especially when dealing with multiple languages and complex projects. This guide explains how to configure these settings, including specifying your project's languages, defining a reference language, and setting key order preferences.

Specifying project languages​

By specifying the list of languages in your branchlate.json configuration file, you ensure consistent language management across your project. This allows Branchlate to automatically create or remove languages as needed and generate translation files for specified languages.

Defining languages​

You can define the languages for your project using the languages field in your branchlate.json:

{
  "projectId": "super-project",
  "organisationId": "super-organisation",
  "languageFilePattern": "i18n/{languageCode}.json",
  "languages": ["en", "fr", "de", "it"]
}

In this configuration:

  • languages: An array specifying the language codes used in your project.

Benefits of specifying languages​

  • Consistency: Ensures that all specified languages are managed consistently across the project.
  • Automation: Branchlate can automatically create translation files for the specified languages during sync operations.
  • Simplification: Reduces manual management of language files and minimizes the risk of missing translations.

Overriding languages in sub-projects​

If you're using sub-projects, you can override the languages field for each sub-project. This allows different sub-projects to support different sets of languages.

Example​

{
  "projectId": "super-project",
  "organisationId": "super-organisation",
  "languages": ["en", "fr", "de", "it"],
  "subProjects": [
    {
      "subProjectId": "emails",
      "languageFilePattern": "i18n/emails/{languageCode}.json",
      "languages": ["en", "fr"]
    },
    {
      "subProjectId": "website",
      "languageFilePattern": "i18n/website/{languageCode}.json"
      // Inherits languages from the main project: ["en", "fr", "de", "it"]
    }
  ]
}

In this configuration:

  • The main project specifies languages: "en", "fr", "de", "it".
  • Sub-project emails overrides the languages to only "en" and "fr".
  • Sub-project website inherits the languages from the main project.

Reference language​

A reference language is the primary language defined for your project in branchlate.json. This language serves as the authoritative source for all translation keys. Any keys found in other languages but missing in the reference language will be removed during sync operations. This simplifies the translation process by keeping translation files in sync with a single, designated reference.

Defining a reference language​

In your branchlate.json, you can specify a reference language:

{
  "projectId": "super-project",
  "organisationId": "super-organisation",
  "languages": ["en", "fr", "de", "it"],
  "referenceLanguage": "en"
}

In this example:

  • referenceLanguage is set to "en" (English).
  • During sync operations, only the keys present in the English files will be retained. Any keys missing in the English files but present in other language files will be removed.

Benefits of a reference language​

  • Simplified key management: Delete a key from the reference language, and Branchlate will automatically remove it from other languages during the next sync.
  • Consistency: Ensures all translations are aligned with the reference language.

Overriding reference language in sub-projects​

Sub-projects can override the referenceLanguage if needed.

Example​

{
  "projectId": "super-project",
  "organisationId": "super-organisation",
  "referenceLanguage": "en",
  "subProjects": [
    {
      "subProjectId": "app",
      "languageFilePattern": "i18n/app/{languageCode}.json"
      // Inherits referenceLanguage: "en"
    },
    {
      "subProjectId": "marketing",
      "languageFilePattern": "i18n/marketing/{languageCode}.json",
      "referenceLanguage": "fr"
    }
  ]
}

In this configuration:

  • Sub-project app uses "en" as the reference language.
  • Sub-project marketing overrides the reference language to "fr".

Controlling translation key order​

By default, Branchlate orders translation keys alphabetically in each language file, which helps users locate keys quickly. However, there are cases where a specific order is required—such as translating structured content like an email where certain keys need to appear first.

Preserving key order from the reference language​

To customize key ordering, Branchlate provides the keepsReferenceLanguageOrder option. When enabled, this setting preserves the order of keys in the reference language across all other language files.

Example​

{
  "projectId": "super-project",
  "organisationId": "super-organisation",
  "referenceLanguage": "en",
  "keepsReferenceLanguageOrder": true
}

In this configuration:

  • keepsReferenceLanguageOrder is set to true.
  • Translation keys in the English file will maintain their order across all languages.

Use case for key order​

Consider an email template where the order of keys matters:

{
  "subject": "Reset your password",
  "title": "Reset Password",
  "paragraph1": "Enter your email address and we'll send you a link to reset your password.",
  "paragraph2": "If you did not request a password reset, please ignore this email."
}

With keepsReferenceLanguageOrder enabled, other language files will follow the order defined in the English (reference) file rather than defaulting to alphabetical order.

tip

Using keepsReferenceLanguageOrder is particularly useful for content like emails or structured documents, where key order impacts readability and context.

Overriding key order in sub-projects​

Sub-projects can also override the keepsReferenceLanguageOrder setting.

Example​

{
  "projectId": "super-project",
  "organisationId": "super-organisation",
  "referenceLanguage": "en",
  "keepsReferenceLanguageOrder": true,
  "subProjects": [
    {
      "subProjectId": "legal",
      "languageFilePattern": "i18n/legal/{languageCode}.json",
      "keepsReferenceLanguageOrder": false
    }
  ]
}

In this configuration:

  • Sub-project legal sets keepsReferenceLanguageOrder to false, so keys will be ordered alphabetically.
  • Other sub-projects inherit the main project's setting of keepsReferenceLanguageOrder: true.

Summary of key settings​

  • languages: Defines the list of languages used in the project or sub-projects.
  • referenceLanguage: Sets the primary language file that Branchlate uses to determine which keys should be retained or removed during syncs.
  • keepsReferenceLanguageOrder: Controls whether the key order in the reference language is preserved in other languages.
  • Sub-project configurations: Sub-projects can override languages, referenceLanguage, and keepsReferenceLanguageOrder as needed.

These settings help streamline the translation process by keeping language files aligned, organized, and relevant.

Best practices​

  • Specify languages explicitly: Defining the languages array ensures consistency and allows Branchlate to manage language files automatically.
  • Use a reference language: Setting a referenceLanguage simplifies key management and ensures all translations are aligned.
  • Control key order when necessary: Use keepsReferenceLanguageOrder when the order of keys affects the content's meaning or presentation.
  • Override settings per sub-project: Utilize sub-project overrides to accommodate different requirements across various parts of your project.

Additional considerations​

  • Language codes: Use standard ISO language codes (e.g., en, fr, de) to ensure compatibility and consistency.
  • Adding or removing languages: Update the languages array in your branchlate.json when you need to add or remove languages. Branchlate will handle the creation or deletion of language files accordingly.
  • Sub-projects with different languages: If certain sub-projects require different sets of languages, specify the languages array within those sub-projects.

Example of a comprehensive branchlate.json​

{
  "projectId": "super-project",
  "organisationId": "super-organisation",
  "languages": ["en", "fr", "de", "it"],
  "referenceLanguage": "en",
  "keepsReferenceLanguageOrder": true,
  "subProjects": [
    {
      "subProjectId": "app",
      "languageFilePattern": "i18n/app/{languageCode}.json"
      // Inherits languages, referenceLanguage, and keepsReferenceLanguageOrder
    },
    {
      "subProjectId": "emails",
      "languageFilePattern": "i18n/emails/{languageCode}.json",
      "languages": ["en", "fr"],
      "keepsReferenceLanguageOrder": false
    },
    {
      "subProjectId": "marketing",
      "languageFilePattern": "i18n/marketing/{languageCode}.json",
      "languages": ["en", "fr", "es"],
      "referenceLanguage": "fr",
      "keepsReferenceLanguageOrder": true
    }
  ]
}

In this configuration:

  • Main project: Uses "en", "fr", "de", "it" as languages, with "en" as the reference language, and keeps the reference language order.
  • Sub-project app: Inherits all settings from the main project.
  • Sub-project emails:
    • Languages: "en", "fr".
    • Does not keep the reference language order.
  • Sub-project marketing:
    • Languages: "en", "fr", "es".
    • Reference language: "fr".
    • Keeps the reference language order.

This setup allows for flexible management of translations across different parts of your project.

Next steps​

  • Learn how to configure File Patterns to match your project's structure.
  • Explore Sub-Projects for organizing translations into logical sets.
  • Dive into Key Prefixes for advanced key management.

By effectively managing your project's languages, reference language, and key order settings, you can streamline your translation workflow and ensure consistency across all aspects of your project.

If you have any questions or need further assistance, please refer to the Getting Started guide or contact our support team.