Add translation system documentation for contributors

Co-authored-by: jbtronics <5410681+jbtronics@users.noreply.github.com>

docs/development/index.md

@@ -0,0 +1,24 @@
+---
+title: Development
+layout: default
+nav_order: 10
+has_children: true
+---
+
+# Development Documentation
+
+This section contains documentation for contributors and developers working on Part-DB.
+
+## Contents
+
+- [Translation System](translation.md) - Learn how translations and synonyms work in Part-DB
+
+## Getting Started
+
+For general contributing guidelines, see the [CONTRIBUTING.md](../../CONTRIBUTING.md) file in the root of the repository.
+
+## Additional Resources
+
+- [GitHub Repository](https://github.com/Part-DB/Part-DB-server)
+- [Issue Tracker](https://github.com/Part-DB/Part-DB-server/issues)
+- [Crowdin Translation Platform](https://part-db.crowdin.com/part-db)

docs/development/translation.md

@@ -0,0 +1,231 @@
+---
+title: Translation System
+layout: default
+parent: Development
+nav_order: 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](https://part-db.crowdin.com/part-db), 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 PHP/Twig:
+```twig
+{{ 'part.info.title'|trans }}
+```
+
+In PHP:
+```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.).
+
+### 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
+
+#### Basic Usage
+
+Translation string:
+```
+"Click here to create a new [Category]"
+```
+
+Default output:
+```
+"Click here to create a new Category"
+```
+
+With custom synonym (Category → "Product Type"):
+```
+"Click here to create a new Product Type"
+```
+
+#### Multiple Placeholders
+
+Translation string:
+```
+"This [part] belongs to [category] 'Electronics'"
+```
+
+Default output:
+```
+"This part belongs to category 'Electronics'"
+```
+
+With custom synonyms:
+```
+"This component belongs to product group 'Electronics'"
+```
+
+#### Plural Usage
+
+Translation string:
+```
+"You have 5 [[part]] in 3 [[category]]"
+```
+
+Default output:
+```
+"You have 5 parts in 3 categories"
+```
+
+With custom synonyms (Part → "Component", Category → "Group"):
+```
+"You have 5 components in 3 groups"
+```
+
+#### Case Variations
+
+Translation string:
+```
+"Select a [Category] to view its [[part]]"
+```
+
+This demonstrates:
+- `[Category]` - Capitalized singular (starts sentence or emphasizes)
+- `[[part]]` - Lowercase plural (mid-sentence)
+
+### 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 in Translations
+
+When writing or updating translation strings:
+
+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.
+
+   ✅ Good: `"Delete this [category]?"`
+   
+   ❌ Bad: `"Delete this category?"`
+
+2. **Match the case to context**:
+   - Use capitalized forms (`[Type]`, `[[Type]]`) at the start of sentences or for emphasis
+   - Use lowercase forms (`[type]`, `[[type]]`) in the middle of sentences
+
+3. **Choose singular vs. plural appropriately**:
+   - Use singular for single items: `"Create new [part]"`
+   - Use plural for multiple items or lists: `"Available [[part]]"`
+
+4. **Consistency**: Be consistent with placeholder usage across similar translation strings
+
+5. **Don't overuse**: Only use placeholders for actual entity type names. Don't use them for:
+   - Action verbs (use regular translations)
+   - Specific feature names
+   - UI element names that aren't entity types
+
+### Testing Synonyms
+
+To test how your translations work with synonyms:
+
+1. Go to Settings → Synonyms in Part-DB
+2. Define custom synonyms for the types you're testing
+3. Navigate to pages that use your translation strings
+4. Verify the synonyms appear correctly with proper capitalization and plurality
+
+## 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:
+```php
+$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](https://part-db.crowdin.com/part-db)
+- [Symfony Translation Documentation](https://symfony.com/doc/current/translation.html)
+- [Contributing Guide](../../CONTRIBUTING.md)