Part-DB-server/docs/development/translation.md

title	layout	parent	nav_order
Translation System	default	Development	1

Translation System for Contributors

This document explains how Part-DB's translation system works and how contributors can effectively use it.

Overview

Part-DB uses Symfony's translation system with XLIFF format files. Translations are managed through Crowdin, but understanding the system's features is important for contributors working on code or translations.

Basic Translation Approach

Part-DB uses translation keys rather than translating English strings directly. For example:

• Translation key: part.info.title
• English: "Part Information"
• German: "Bauteil-Informationen"

This approach has several advantages:

• Keys remain stable even if the English text changes
• The same key can have different translations in different contexts
• Keys are organized hierarchically by feature/context

Using Translations in Code

In Twig (short syntax):

{{ 'part.info.title'|trans }}

In Twig (block syntax for longer text):

{% trans %}part.info.title{% endtrans %}

In PHP:

$translator->trans('part.info.title')

Type Synonyms and Placeholders

Part-DB includes a powerful synonym system that allows customizing the names of entity types (like "Category", "Part", "Manufacturer") throughout the interface. This is particularly useful for organizations that prefer different terminology.

How Synonyms Work

Administrators can define custom names for entity types in the settings (Settings → Synonyms). These custom names are then automatically substituted throughout the application using translation placeholders.

Placeholder Syntax

The synonym system uses special placeholders in translation strings that get replaced with the appropriate entity type name:

Placeholder	Meaning	Example Output (Default)	Example Output (with synonym)
[Type]	Singular, capitalized	"Category"	"Product Group"
[[Type]]	Plural, capitalized	"Categories"	"Product Groups"
[type]	Singular, lowercase	"category"	"product group"
[[type]]	Plural, lowercase	"categories"	"product groups"

Where Type is the element type name (e.g., category, part, manufacturer, etc.).

Note for inflected languages: In languages like German where words are inflected (e.g., case declensions), synonyms should be defined in the nominative case (the standard/dictionary form). The placeholders will be substituted as-is, so translations need to be written to work with the nominative form.

Available Element Types

The following element types support synonyms:

• category - Part categories
• part - Electronic parts/components
• manufacturer - Component manufacturers
• supplier - Component suppliers
• storage_location - Physical storage locations (also called storelocation)
• footprint - PCB footprints
• attachment_type - File attachment types
• measurement_unit - Units of measurement
• currency - Currencies
• project - Projects
• And many others (see ElementTypes enum in code)

Examples

Example 1: "Click here to create a new [Category]"

• Default: "Click here to create a new Category"
• With synonym (Category → "Product Type"): "Click here to create a new Product Type"

Example 2: "You have 5 [[part]] in 3 [[category]]"

• Default: "You have 5 parts in 3 categories"
• With synonyms (Part → "Component", Category → "Group"): "You have 5 components in 3 groups"

Technical Implementation

The synonym system is implemented through several components:

1. SynonymSettings (src/Settings/SynonymSettings.php): Stores user-defined synonyms
2. ElementTypeNameGenerator (src/Services/ElementTypeNameGenerator.php): Generates localized labels
3. RegisterSynonymsAsTranslationParametersListener (src/EventListener/RegisterSynonymsAsTranslationParametersListener.php): Registers placeholders globally

The system automatically:

• Generates placeholders for all element types at application startup
• Handles capitalization properly for different languages
• Falls back to default translations if no synonym is defined
• Caches placeholder values for performance

Guidelines for Using Synonyms

When writing translation strings:

• Use placeholders for entity types (✅ "Delete this [category]?" ❌ "Delete this category?")
• Match case to context: capitalized ([Type], [[Type]]) at sentence start, lowercase ([type], [[type]]) mid-sentence
• Use singular for single items, plural for multiple items
• Only use for actual entity type names, not for actions or feature names

Translation Parameters

In addition to synonym placeholders, Part-DB uses standard Symfony translation parameters for dynamic values:

"You have %count% parts selected"

Parameters are passed when calling the translation:

$translator->trans('parts.selected', ['%count%' => 5])

Important: Parameters use %paramName% syntax, while synonym placeholders use [Type] or [[Type]] syntax.

Translation Files

Translation files are located in the translations/ directory and use XLIFF format:

• messages.en.xlf - English translations
• messages.de.xlf - German translations
• messages.{locale}.xlf - Other languages

The XLIFF format includes:

• Source key (translation key)
• Target (translated text)
• Notes (file locations where the key is used)

Best Practices

1. Use translation keys, not hardcoded text: Always use translation keys for any user-facing text
2. Organize keys hierarchically: Use dots to namespace keys (e.g., part.info.title)
3. Use synonym placeholders for entity types: This gives administrators flexibility
4. Test with different synonym configurations: Ensure your text works with custom names
5. Be consistent: Follow existing patterns for similar functionality
6. Check other languages: Look at how similar keys are translated in other languages (via Crowdin's "Other languages" dropdown)

Resources

• Crowdin Part-DB Project
• Symfony Translation Documentation
• Contributing Guide