Skip to content

Commit 0433651

Browse files
Copilotjbtronics
Copilot
and
jbtronics
committed
Add translation system documentation for contributors
Co-authored-by: jbtronics <[email protected]>
1 parent 01c368c commit 0433651

File tree

3 files changed

+257
-0
lines changed

3 files changed

+257
-0
lines changed

‎CONTRIBUTING.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,8 @@ If you want to start translation for a new language that does not have an entry
1717
Part-DB uses translation keys (e.g. part.info.title) that are sorted by their usage, so you will most likely have to lookup, how the key
1818
was translated in other languages (this is possible via the "Other languages" dropdown in the translation editor).
1919

20+
For detailed information about the translation system, including how to use type synonyms and placeholders, see the [Translation System Documentation](docs/development/translation.md).
21+
2022
## Project structure
2123
Part-DB uses Symfony's recommended [project structure](https://symfony.com/doc/current/best_practices.html).
2224
Interesting folders are:

‎docs/development/index.md‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
---
2+
title: Development
3+
layout: default
4+
nav_order: 10
5+
has_children: true
6+
---
7+
8+
# Development Documentation
9+
10+
This section contains documentation for contributors and developers working on Part-DB.
11+
12+
## Contents
13+
14+
- [Translation System](translation.md) - Learn how translations and synonyms work in Part-DB
15+
16+
## Getting Started
17+
18+
For general contributing guidelines, see the [CONTRIBUTING.md](../../CONTRIBUTING.md) file in the root of the repository.
19+
20+
## Additional Resources
21+
22+
- [GitHub Repository](https://github.com/Part-DB/Part-DB-server)
23+
- [Issue Tracker](https://github.com/Part-DB/Part-DB-server/issues)
24+
- [Crowdin Translation Platform](https://part-db.crowdin.com/part-db)

‎docs/development/translation.md‎

Lines changed: 231 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,231 @@
1+
---
2+
title: Translation System
3+
layout: default
4+
parent: Development
5+
nav_order: 1
6+
---
7+
8+
# Translation System for Contributors
9+
10+
This document explains how Part-DB's translation system works and how contributors can effectively use it.
11+
12+
## Overview
13+
14+
Part-DB uses Symfony's translation system with XLIFF format files. Translations are managed through [Crowdin](https://part-db.crowdin.com/part-db), but understanding the system's features is important for contributors working on code or translations.
15+
16+
## Basic Translation Approach
17+
18+
Part-DB uses translation keys rather than translating English strings directly. For example:
19+
20+
- Translation key: `part.info.title`
21+
- English: "Part Information"
22+
- German: "Bauteil-Informationen"
23+
24+
This approach has several advantages:
25+
- Keys remain stable even if the English text changes
26+
- The same key can have different translations in different contexts
27+
- Keys are organized hierarchically by feature/context
28+
29+
### Using Translations in Code
30+
31+
In PHP/Twig:
32+
```twig
33+
{{ 'part.info.title'|trans }}
34+
```
35+
36+
In PHP:
37+
```php
38+
$translator->trans('part.info.title')
39+
```
40+
41+
## Type Synonyms and Placeholders
42+
43+
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.
44+
45+
### How Synonyms Work
46+
47+
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.
48+
49+
### Placeholder Syntax
50+
51+
The synonym system uses special placeholders in translation strings that get replaced with the appropriate entity type name:
52+
53+
| Placeholder | Meaning | Example Output (Default) | Example Output (with synonym) |
54+
|------------|---------|-------------------------|------------------------------|
55+
| `[Type]` | Singular, capitalized | "Category" | "Product Group" |
56+
| `[[Type]]` | Plural, capitalized | "Categories" | "Product Groups" |
57+
| `[type]` | Singular, lowercase | "category" | "product group" |
58+
| `[[type]]` | Plural, lowercase | "categories" | "product groups" |
59+
60+
Where `Type` is the element type name (e.g., `category`, `part`, `manufacturer`, etc.).
61+
62+
### Available Element Types
63+
64+
The following element types support synonyms:
65+
66+
- `category` - Part categories
67+
- `part` - Electronic parts/components
68+
- `manufacturer` - Component manufacturers
69+
- `supplier` - Component suppliers
70+
- `storage_location` - Physical storage locations (also called `storelocation`)
71+
- `footprint` - PCB footprints
72+
- `attachment_type` - File attachment types
73+
- `measurement_unit` - Units of measurement
74+
- `currency` - Currencies
75+
- `project` - Projects
76+
- And many others (see `ElementTypes` enum in code)
77+
78+
### Examples
79+
80+
#### Basic Usage
81+
82+
Translation string:
83+
```
84+
"Click here to create a new [Category]"
85+
```
86+
87+
Default output:
88+
```
89+
"Click here to create a new Category"
90+
```
91+
92+
With custom synonym (Category → "Product Type"):
93+
```
94+
"Click here to create a new Product Type"
95+
```
96+
97+
#### Multiple Placeholders
98+
99+
Translation string:
100+
```
101+
"This [part] belongs to [category] 'Electronics'"
102+
```
103+
104+
Default output:
105+
```
106+
"This part belongs to category 'Electronics'"
107+
```
108+
109+
With custom synonyms:
110+
```
111+
"This component belongs to product group 'Electronics'"
112+
```
113+
114+
#### Plural Usage
115+
116+
Translation string:
117+
```
118+
"You have 5 [[part]] in 3 [[category]]"
119+
```
120+
121+
Default output:
122+
```
123+
"You have 5 parts in 3 categories"
124+
```
125+
126+
With custom synonyms (Part → "Component", Category → "Group"):
127+
```
128+
"You have 5 components in 3 groups"
129+
```
130+
131+
#### Case Variations
132+
133+
Translation string:
134+
```
135+
"Select a [Category] to view its [[part]]"
136+
```
137+
138+
This demonstrates:
139+
- `[Category]` - Capitalized singular (starts sentence or emphasizes)
140+
- `[[part]]` - Lowercase plural (mid-sentence)
141+
142+
### Technical Implementation
143+
144+
The synonym system is implemented through several components:
145+
146+
1. **SynonymSettings** (`src/Settings/SynonymSettings.php`): Stores user-defined synonyms
147+
2. **ElementTypeNameGenerator** (`src/Services/ElementTypeNameGenerator.php`): Generates localized labels
148+
3. **RegisterSynonymsAsTranslationParametersListener** (`src/EventListener/RegisterSynonymsAsTranslationParametersListener.php`): Registers placeholders globally
149+
150+
The system automatically:
151+
- Generates placeholders for all element types at application startup
152+
- Handles capitalization properly for different languages
153+
- Falls back to default translations if no synonym is defined
154+
- Caches placeholder values for performance
155+
156+
### Guidelines for Using Synonyms in Translations
157+
158+
When writing or updating translation strings:
159+
160+
1. **Use synonyms for entity type references**: When referring to entity types like categories, parts, manufacturers, etc., use the synonym placeholders instead of hardcoding the type name.
161+
162+
✅ Good: `"Delete this [category]?"`
163+
164+
❌ Bad: `"Delete this category?"`
165+
166+
2. **Match the case to context**:
167+
- Use capitalized forms (`[Type]`, `[[Type]]`) at the start of sentences or for emphasis
168+
- Use lowercase forms (`[type]`, `[[type]]`) in the middle of sentences
169+
170+
3. **Choose singular vs. plural appropriately**:
171+
- Use singular for single items: `"Create new [part]"`
172+
- Use plural for multiple items or lists: `"Available [[part]]"`
173+
174+
4. **Consistency**: Be consistent with placeholder usage across similar translation strings
175+
176+
5. **Don't overuse**: Only use placeholders for actual entity type names. Don't use them for:
177+
- Action verbs (use regular translations)
178+
- Specific feature names
179+
- UI element names that aren't entity types
180+
181+
### Testing Synonyms
182+
183+
To test how your translations work with synonyms:
184+
185+
1. Go to Settings → Synonyms in Part-DB
186+
2. Define custom synonyms for the types you're testing
187+
3. Navigate to pages that use your translation strings
188+
4. Verify the synonyms appear correctly with proper capitalization and plurality
189+
190+
## Translation Parameters
191+
192+
In addition to synonym placeholders, Part-DB uses standard Symfony translation parameters for dynamic values:
193+
194+
```
195+
"You have %count% parts selected"
196+
```
197+
198+
Parameters are passed when calling the translation:
199+
```php
200+
$translator->trans('parts.selected', ['%count%' => 5])
201+
```
202+
203+
Important: Parameters use `%paramName%` syntax, while synonym placeholders use `[Type]` or `[[Type]]` syntax.
204+
205+
## Translation Files
206+
207+
Translation files are located in the `translations/` directory and use XLIFF format:
208+
209+
- `messages.en.xlf` - English translations
210+
- `messages.de.xlf` - German translations
211+
- `messages.{locale}.xlf` - Other languages
212+
213+
The XLIFF format includes:
214+
- Source key (translation key)
215+
- Target (translated text)
216+
- Notes (file locations where the key is used)
217+
218+
## Best Practices
219+
220+
1. **Use translation keys, not hardcoded text**: Always use translation keys for any user-facing text
221+
2. **Organize keys hierarchically**: Use dots to namespace keys (e.g., `part.info.title`)
222+
3. **Use synonym placeholders for entity types**: This gives administrators flexibility
223+
4. **Test with different synonym configurations**: Ensure your text works with custom names
224+
5. **Be consistent**: Follow existing patterns for similar functionality
225+
6. **Check other languages**: Look at how similar keys are translated in other languages (via Crowdin's "Other languages" dropdown)
226+
227+
## Resources
228+
229+
- [Crowdin Part-DB Project](https://part-db.crowdin.com/part-db)
230+
- [Symfony Translation Documentation](https://symfony.com/doc/current/translation.html)
231+
- [Contributing Guide](../../CONTRIBUTING.md)

0 commit comments

Comments
 (0)