Sub-Projects

In Branchlate, sub-projects allow you to divide a main project into multiple logical sets of translations. This feature is especially useful for large projects where different sections or features of your application require their own translation files. By organizing translations into sub-projects, you can improve maintainability, enhance collaboration, and tailor configurations to specific needs.

What are sub-projects?

Sub-projects are subdivisions of a main project in Branchlate, each representing a distinct set of translation keys. They enable you to:

Organize translations logically: Group related translations together (e.g., by feature, module, or component).
Manage configurations individually: Specify different languages, reference languages, or key order settings per sub-project.
Improve collaboration: Allow different teams to work on separate sub-projects without affecting others.

Defining sub-projects using patterns

Branchlate introduces a flexible way to define sub-projects using patterns in your branchlate.json configuration. By using placeholders like {subProjectId}, you can automatically detect and manage multiple sub-projects without listing each one individually.

Using the `subProjects` pattern

You can define sub-projects by setting the subProjects field to a pattern that includes {subProjectId}. This approach simplifies configuration, especially when you have many sub-projects with similar structures.

Example 1: Sub-projects organized by feature

Suppose your project has the following directory structure:

i18n/
├── common/
│   ├── en.json
│   ├── fr.json
│   ├── de.json
│   └── it.json
├── auth/
│   ├── en.json
│   ├── fr.json
│   ├── de.json
│   └── it.json
└── dashboard/
    ├── en.json
    ├── fr.json
    ├── de.json
    └── it.json

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 the pattern "i18n/{subProjectId}/{languageCode}.json".
Branchlate automatically detects sub-projects (common, auth, dashboard) based on the directories under i18n/.
languages specifies the list of languages used across all sub-projects.

Example 2: Sub-projects with language code first

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

Directory structure:

i18n/
├── en/
│   ├── common.json
│   ├── auth.json
│   └── dashboard.json
├── fr/
│   ├── common.json
│   ├── auth.json
│   └── dashboard.json
├── de/
│   ├── common.json
│   ├── auth.json
│   └── dashboard.json
└── it/
    ├── common.json
    ├── auth.json
    └── dashboard.json

Configuration:

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

How Branchlate handles sub-project patterns

Detection: Branchlate identifies sub-projects by matching the {subProjectId} placeholder in the pattern.
Syncing: Each sub-project is synced separately, maintaining distinct sets of translation keys.
Flexibility: You can adjust the pattern to fit your project's directory structure.

Specifying sub-projects individually

In some cases, you may need to define sub-projects individually, especially when they have different configurations, file formats, or structures.

When to specify sub-projects individually

Different file formats: Sub-projects use different file extensions (e.g., .json, .md, .txt).
Unique structures: Sub-projects have varying directory structures or require special handling.
Specific settings: Sub-projects need to override main project settings (e.g., languages, reference language).

Example: Sub-projects with different configurations

Suppose you have the following directory structure:

locales/
├── common/
│   ├── en.json
│   ├── fr.json
│   ├── de.json
│   └── it.json
├── emails/
│   ├── en.txt
│   ├── fr.txt
├── legal/
│   ├── en/
│   │   ├── terms.md
│   │   └── privacy.md
│   ├── fr/
│   │   ├── conditions.md
│   │   └── confidentialite.md

Your branchlate.json configuration would be:

{
  "projectId": "my-project",
  "organisationId": "my-organisation",
  "languages": ["en", "fr", "de", "it"],
  "subProjects": [
    {
      "subProjectId": "common",
      "languageFilePattern": "locales/common/{languageCode}.json"
      // Inherits languages from main project
    },
    {
      "subProjectId": "emails",
      "languageFilePattern": "locales/emails/{languageCode}.txt",
      "languages": ["en", "fr"]
    },
    {
      "subProjectId": "legal",
      "languageFilePattern": "locales/legal/{languageCode}/{keyPrefix}.md",
      "languages": ["en", "fr"],
      "keyPrefixMappings": [
        {
          "en": "terms",
          "fr": "conditions"
        },
        {
          "en": "privacy",
          "fr": "confidentialite"
        }
      ]
    }
  ]
}

In this configuration:

Sub-project common:
- Uses JSON files.
- Inherits languages from the main project.
Sub-project emails:
- Uses text files (.txt).
- Specifies languages "en" and "fr" only.
Sub-project legal:
- Uses Markdown files (.md).
- Contains translated filenames using keyPrefixMappings.
- Employs {keyPrefix} in the languageFilePattern.

Explanation of `keyPrefixMappings`

The keyPrefixMappings field allows you to map keyPrefix values to translated filenames. This is useful when your filenames are translated for SEO or organizational purposes.

In the example:

English files:
- locales/legal/en/terms.md
- locales/legal/en/privacy.md
French files:
- locales/legal/fr/conditions.md
- locales/legal/fr/confidentialite.md
Mappings:
- { "en": "terms", "fr": "conditions" }
- { "en": "privacy", "fr": "confidentialite" }

Branchlate uses these mappings to correctly associate files across languages.

Best practices for managing sub-projects

To make the most of sub-projects, consider the following best practices:

Choose the appropriate sub-project definition method

Use patterns when:
- Sub-projects have similar structures.
- You want to simplify configuration.
- All sub-projects share the same settings.
Specify individually when:
- Sub-projects have different file formats or structures.
- You need to override settings for specific sub-projects.
- You require advanced configurations like keyPrefixMappings.

Maintain consistent naming conventions

Use clear and descriptive subProjectId values (e.g., common, auth, dashboard).
Ensure directory names match the {subProjectId} placeholders in your patterns.

Organize translations logically

Group related translations together to improve maintainability.
Separate translations by feature, module, or content type.

Override settings thoughtfully

Only override settings in sub-projects when necessary.
Inherit from the main project to maintain consistency where possible.

Additional considerations

Combining sub-projects with key prefixes

You can use {keyPrefix} within sub-projects to handle more complex file structures.

Example

content/
├── blog/
│   ├── en/
│   │   ├── post1.md
│   │   └── post2.md
│   └── fr/
│       ├── article1.md
│       └── article2.md

Configuration:

{
  "projectId": "my-project",
  "organisationId": "my-organisation",
  "languages": ["en", "fr"],
  "subProjects": [
    {
      "subProjectId": "blog",
      "languageFilePattern": "content/blog/{languageCode}/{keyPrefix}.md",
      "keyPrefixMappings": [
        {
          "en": "post1",
          "fr": "article1"
        },
        {
          "en": "post2",
          "fr": "article2"
        }
      ]
    }
  ]
}

Using multiple placeholders

Combine {subProjectId}, {languageCode}, and {keyPrefix} as needed to match your directory structure.
Ensure your patterns accurately reflect the file paths in your project.

Summary

Sub-projects in Branchlate provide a powerful way to organize and manage your translations, especially in large or complex projects. By using patterns or specifying sub-projects individually, you can tailor the translation workflow to fit your project's needs.

Patterns simplify configuration when sub-projects share similar structures.
Individual specifications offer flexibility for sub-projects with unique requirements.
Best practices help maintain consistency, improve collaboration, and enhance maintainability.

Next steps

Explore File Patterns to understand how to configure patterns in your project.
Learn about Key Prefixes for advanced key management and handling translated filenames.
Review Languages and Key Order to manage languages and key ordering effectively.

By effectively utilizing sub-projects, you can streamline your translation management, accommodate diverse project requirements, and maintain a well-organized codebase.

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

What are sub-projects?​

Defining sub-projects using patterns​

Using the subProjects pattern​

Example 1: Sub-projects organized by feature​

Example 2: Sub-projects with language code first​

How Branchlate handles sub-project patterns​

Specifying sub-projects individually​

When to specify sub-projects individually​

Example: Sub-projects with different configurations​

Explanation of keyPrefixMappings​

Best practices for managing sub-projects​

Choose the appropriate sub-project definition method​

Maintain consistent naming conventions​

Organize translations logically​

Override settings thoughtfully​

Additional considerations​

Combining sub-projects with key prefixes​

Example​

Using multiple placeholders​

Summary​

Next steps​