Skip to main content

File Patterns

In Branchlate, the file pattern specified in your branchlate.json configuration determines how translation files are located and processed. By understanding and utilizing different file patterns, you can align Branchlate with your project's structure, whether it's a straightforward flat structure, divided into sub-projects, or a complex setup with nested directories and key prefixes.

Branchlate File Pattern
Diagram illustrating standard, sub-project, and key-prefixed file patterns.

The diagram above compares three common file patterns:

  1. Standard file pattern: Suitable for projects where all translations for a language are stored in a single file. Each language has its own file, making it easy to manage flat translation structures.
  2. Sub-project file pattern: Ideal for organizing translations into logical subsets, such as features or components. This pattern allows you to manage multiple translation files per language.
  3. Key-prefixed file pattern: Useful for more granular control, especially for content-heavy projects like Next.js, where individual files correspond to specific translation keys. This pattern supports nested directories and flexible key structures, allowing hierarchical keys like data.privacy-policy.

By understanding and leveraging these patterns, you can tailor Branchlate to fit your project's specific requirements while maintaining consistency and efficiency.

Standard file patterns​

The most common file pattern uses the {languageCode} placeholder to specify where your translation files are located. This is suitable for projects where each language's translations are stored in a single file.

Example​

Suppose your project has the following directory structure:

i18n/
├── en.json
├── fr.json
├── de.json
└── it.json

Each file (e.g., en.json) contains all the translation keys and values for that language.

Your branchlate.json configuration would be:

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

In this configuration:

  • languageFilePattern is set to "i18n/{languageCode}.json".
  • languages specifies the list of languages used in the project. This helps Branchlate manage languages consistently and can create or remove translation files automatically.

This pattern is straightforward and works well for most projects with flat translation structures.

Sub-project file patterns​

For larger projects or those with distinct modules or features, you might want to organize your translations into sub-projects. Sub-projects allow you to split translations into logical sets, improving organization and maintainability.

Defining sub-projects using patterns​

You can define sub-projects using a file pattern that includes the {subProjectId} placeholder. This approach simplifies configuration, especially when you have many sub-projects.

Example​

Suppose your project has the following directory structure:

i18n/
├── common/
│   ├── en.json
│   ├── fr.json
│   ├── de.json
│   └── it.json
├── featureX/
│   ├── en.json
│   ├── fr.json
│   ├── de.json
│   └── it.json
└── featureY/
    ├── en.json
    ├── fr.json
    ├── de.json
    └── it.json

Each sub-directory under i18n/ represents a sub-project (common, featureX, featureY), and contains translation files for each language.

Your branchlate.json configuration would be:

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

In this configuration:

  • subProjects is set to a pattern "i18n/{subProjectId}/{languageCode}.json".
  • Branchlate will automatically detect sub-projects based on the directories under i18n/.
  • languages specifies the list of languages used across all sub-projects.

How sub-projects are handled​

  • Branchlate identifies each sub-project by the folder name matching {subProjectId}.
  • For each sub-project, it syncs the translations found in the corresponding language files.
  • This pattern simplifies the configuration, especially when adding new sub-projects.

Alternative sub-project patterns​

If your directory structure places the language code before the sub-project, you can adjust the pattern accordingly.

Example​

Directory structure:

i18n/
├── en/
│   ├── common.json
│   ├── featureX.json
│   └── featureY.json
├── fr/
│   ├── common.json
│   ├── featureX.json
│   └── featureY.json
├── de/
│   ├── common.json
│   ├── featureX.json
│   └── featureY.json
└── it/
    ├── common.json
    ├── featureX.json
    └── featureY.json

Configuration:

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

This pattern is flexible and can be adjusted to match your project's structure.

Specifying sub-projects individually​

If you have sub-projects with different file formats or structures, you can specify each sub-project individually in an array.

Example​

{
  "projectId": "my-project",
  "organisationId": "my-organisation",
  "subProjects": [
    {
      "subProjectId": "common",
      "languageFilePattern": "i18n/common/{languageCode}.json",
      "languages": ["en", "fr", "de", "it"]
    },
    {
      "subProjectId": "emails",
      "languageFilePattern": "i18n/emails/{languageCode}.txt",
      "languages": ["en", "fr"]
    }
  ]
}

In this configuration:

  • Sub-project common uses JSON files and includes four languages.
  • Sub-project emails uses text files and includes only English and French.

This approach provides flexibility when sub-projects have varying requirements.

Key-prefixed file patterns​

For projects with complex file structures, such as when each translation key corresponds to a separate file, you can use the {keyPrefix} placeholder in your file pattern. This is particularly useful for managing content like markdown files or Next.js pages.

Brief overview​

When you have a directory structure where each file represents a translation key, you can use {keyPrefix} in your languageFilePattern.

Example​

Directory structure:

markdown-files/
├── en/
│   ├── about-us.md
│   ├── contact.md
│   └── faq.md
└── fr/
    ├── a-propos-de-nous.md
    ├── contact.md
    └── faq.md

Configuration:

{
  "projectId": "my-project",
  "organisationId": "my-organisation",
  "languageFilePattern": "markdown-files/{languageCode}/{keyPrefix}.md",
  "languages": ["en", "fr"]
}

In this configuration:

  • {keyPrefix} represents the filename without extension (e.g., about-us, contact).
  • Branchlate uses the keyPrefix as the translation key and the file content as the translation value.

For a detailed explanation of key prefixes and advanced features like keyPrefixMappings, refer to the Key Prefixes page.

Comparing sub-projects and key prefixes​

While both sub-projects and key prefixes help organize translations, they serve different purposes and are suited for different scenarios.

Sub-projects​

  • Purpose: Organize translations into logical subsets, such as features or components.
  • Use case: When you have multiple translation files per language, each representing a distinct module or feature.
  • Advantages:
    • Improves organization and maintainability.
    • Allows for different configurations per sub-project (e.g., different languages, file formats).
  • Considerations:
    • Best when translations are grouped by logical sets.

Key prefixes​

  • Purpose: Generate translation keys based on file paths, suitable for granular control.
  • Use case: When each file corresponds to a translation key, often in content-heavy applications.
  • Advantages:
    • Simplifies key management by aligning keys with file structure.
    • Supports hierarchical keys through nested directories.
  • Considerations:
    • May require additional configuration for features like translated filenames.

When to use one over the other​

  • Use sub-projects when you have distinct modules or features that can be logically separated, and you prefer to manage translations in grouped files.
  • Use key prefixes when you need fine-grained control over individual translation keys, especially when dealing with numerous content files.

Next steps​

  • To learn more about sub-projects and how to configure them in detail, visit the Sub-Projects page.
  • For an in-depth explanation of key prefixes and advanced usage, refer to the Key Prefixes page.
  • To understand how to manage languages and key order, see the Languages and Key Order page.

By configuring the languageFilePattern appropriately, you can tailor Branchlate to fit the specific needs of your project, whether you're dealing with simple JSON files, organizing translations into sub-projects, or managing a complex hierarchy of content files. Leveraging these patterns helps:

  • Handle complex file structures with ease.
  • Automatically generate translation keys based on file paths.
  • Maintain consistency and organization in your translation management.
  • Integrate seamlessly with content-heavy applications or frameworks like Next.js.