Key Prefixes

In Branchlate, key prefixes provide a powerful way to manage translations when dealing with complex file structures, especially in content-heavy projects where each translation key corresponds to a separate file. By using {keyPrefix} in your languageFilePattern, you can automatically generate translation keys based on file paths, maintain hierarchical structures, and handle translated filenames.

---

Understanding key prefixes

A key prefix is a placeholder used in your languageFilePattern to capture parts of the file path and use them as translation keys. This is particularly useful when your project structure involves:

• Multiple files per language, each representing a translation key.
• Nested directories that correspond to hierarchical translation keys.
• Filenames that are consistent or translated across languages.

The {keyPrefix} placeholder tells Branchlate to extract the corresponding part of the file path and use it as part of the translation key.

---

Using {keyPrefix} in file patterns

Single {keyPrefix}

When you have a directory structure where each file represents a translation key, and filenames are the same across languages, you can use a single {keyPrefix} in your languageFilePattern.

Example

Suppose your project has the following directory structure:

content/
├── en/
│   ├── about-us.md
│   ├── contact.md
│   └── faq.md
└── fr/
    ├── about-us.md
    ├── contact.md
    └── faq.md

Your branchlate.json configuration would be:

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

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.

How keys are constructed

• about-us.md in en and fr becomes key: about-us
• contact.md in en and fr becomes key: contact
• faq.md in en and fr becomes key: faq

Since the filenames are the same across languages, there's no need for keyPrefixMappings.

Multiple {keyPrefix} placeholders

If your files are organized in nested directories, you can use multiple {keyPrefix} placeholders to capture the hierarchical structure.

Example

Directory structure:

content/
├── en/
│   ├── blog/
│   │   ├── post1.md
│   │   └── post2.md
│   └── pages/
│       ├── about-us.md
│       └── contact.md
└── fr/
    ├── blog/
    │   ├── post1.md
    │   └── post2.md
    └── pages/
        ├── about-us.md
        └── contact.md

Configuration:

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

How keys are constructed

• The first {keyPrefix} captures the directory (blog, pages).

• The second {keyPrefix} captures the filename without extension (post1, about-us).

• Keys are constructed using dot notation:

  • blog.post1 corresponds to content/en/blog/post1.md and content/fr/blog/post1.md
  • pages.about-us corresponds to content/en/pages/about-us.md and content/fr/pages/about-us.md

Again, since the directory and filenames are the same across languages, there's no need for keyPrefixMappings.

---

Combining key prefixes with sub-projects

You can combine key prefixes with sub-projects to further organize your translations, especially when you want to manage distinct sets of translation keys within a project.

Using key prefixes in sub-projects

Suppose you have a project where you want to separate translations into sub-projects based on content type (e.g., blog, pages), and within each sub-project, you have multiple files representing individual translation keys.

Example

Directory structure:

content/
├── en/
│   ├── blog/
│   │   ├── post1.md
│   │   └── post2.md
│   └── pages/
│       ├── about-us.md
│       └── contact.md
└── fr/
    ├── blog/
    │   ├── post1.md
    │   └── post2.md
    └── pages/
        ├── about-us.md
        └── contact.md

Configuration using sub-projects:

{
  "projectId": "my-project",
  "organisationId": "my-organisation",
  "languages": ["en", "fr"],
  "subProjects": "content/{languageCode}/{subProjectId}/{keyPrefix}.md"
}

In this configuration:

• subProjects is set to "content/{languageCode}/{subProjectId}/{keyPrefix}.md".
• {subProjectId} captures the directory after the language code (blog, pages).
• {keyPrefix} captures the filename without extension (post1, about-us).

How sub-projects and keys are constructed

• Sub-projects:

  • blog sub-project includes all files under content/{languageCode}/blog/.
  • pages sub-project includes all files under content/{languageCode}/pages/.

• Translation keys within each sub-project:

  • For sub-project blog:

    • post1.md becomes key: post1
    • post2.md becomes key: post2

  • For sub-project pages:

    • about-us.md becomes key: about-us
    • contact.md becomes key: contact

Pros and cons of combining key prefixes with sub-projects

Pros:

• Improved organization: Separates translations into logical groups, making it easier to manage large projects.
• Granular control: Allows different configurations or settings per sub-project if needed.
• Flexibility: Can accommodate different languages or settings for each sub-project.

Cons:

• Complexity: Adds an extra layer of configuration, which may be unnecessary for simpler projects.
• Maintenance: Requires careful management of sub-projects and key prefixes to ensure consistency.

Alternative configuration without sub-projects

If you prefer not to use sub-projects, you can use multiple {keyPrefix} placeholders in your languageFilePattern:

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

In this case:

• The first {keyPrefix} captures the directory (blog, pages).
• The second {keyPrefix} captures the filename without extension (post1, about-us).
• Keys are constructed using dot notation, such as blog.post1.

Pros:

• Simplicity: Fewer configuration fields to manage.
• Hierarchical keys: Maintains a hierarchy in the translation keys.

Cons:

• Lack of separation: All translations are part of the main project, without distinct sub-projects.
• Limited configurations: Cannot set different settings per group of translations.

Choosing between sub-projects and key prefixes

When deciding whether to combine key prefixes with sub-projects or use key prefixes alone, consider the following:

• Use sub-projects with key prefixes when:

  • You need to manage distinct sets of translations separately.
  • Different sub-projects require different configurations (e.g., languages, reference languages).
  • You want to enhance organization and collaboration among teams.

• Use key prefixes alone when:

  • The project is relatively simple, and all translations can be managed together.
  • You prefer hierarchical keys without the need for separate sub-project configurations.
  • Consistency across all translations is desired.

---

Key prefix mappings in sub-projects

You can also use keyPrefixMappings within sub-projects to handle translated filenames or directories.

Example

Configuration:

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

In this configuration:

• Sub-project blog uses keyPrefixMappings to map filenames that differ between languages.
• Sub-project pages does not require mappings as filenames are consistent.

---

Advantages of combining key prefixes with sub-projects

• Enhanced organization: Sub-projects allow you to group related translations, while key prefixes manage the hierarchical structure within those groups.
• Custom configurations: Set different languages, reference languages, or key order settings per sub-project.
• Scalability: Easier to manage large projects with numerous translations.

Considerations when combining key prefixes with sub-projects

• Increased complexity: More configuration can lead to complexity; ensure your team understands the structure.
• Consistent conventions: Maintain consistent naming and organization to prevent confusion.
• Testing: Thoroughly test your configurations to ensure translations are correctly associated and synced.

---

Best practices

• Plan your structure: Before configuring, plan how you want to organize translations using sub-projects and key prefixes.
• Use meaningful names: Choose descriptive subProjectId values and filenames.
• Document configurations: Keep documentation of your branchlate.json settings for team reference.
• Regularly sync and test: Sync translations frequently and test the output to catch any issues early.

---

Next steps

• Return to File Patterns to review how key prefixes and sub-projects fit within overall configurations.
• Explore Languages and Key Order to manage languages and key ordering.
• Review Sub-Projects for more details on organizing translations into logical subsets.

---

By effectively combining key prefixes with sub-projects, you can tailor Branchlate to handle complex file structures, translated filenames, and hierarchical translation keys, enhancing your project's internationalization capabilities and organization.

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