---
title: Synonym System
layout: default
parent: Usage
nav_order: 13
---

# Synonym System

Part-DB includes a powerful synonym system that allows you to customize the terminology used throughout the application. This is especially useful when using Part-DB in contexts other than electronics, or when you want to adapt the interface to your organization's specific vocabulary.

1. TOC
{:toc}

## What is the Synonym System?

The synonym system allows you to replace Part-DB's standard terminology with your own preferred terms. For example:
- Change "Part" to "Product", "Component", or "Item"
- Change "Category" to "Group", "Type", or "Class"
- Change "Manufacturer" to "Supplier", "Vendor", or "Brand"

These custom terms (synonyms) are applied throughout the user interface, making Part-DB feel more natural for your specific use case.

## Important Notes

{: .warning-title }
> Experimental Feature
>
> The synonym system is currently **experimental**. While it works in most places throughout Part-DB, there may be some locations where the default terms still appear. The synonym system is being continuously improved.

## Configuring Synonyms

To configure synonyms, you need administrator permissions:

1. Navigate to `Tools -> System -> Settings`
2. Find and click on "Synonyms" in the settings menu
3. You'll see the synonym configuration interface

### Adding a Synonym

To add a new synonym:

1. Click the "Add Entry" button in the synonym settings
2. Select the **Type** (element type) you want to create a synonym for
3. Select the **Language** for which the synonym applies
4. Enter the **Singular** form of your synonym
5. Enter the **Plural** form of your synonym
6. Click "Save" to apply the changes

### Available Element Types

You can create synonyms for the following element types:

| Element Type        | Default Term (EN)     | Example Use Cases                             |
|--------------------|-----------------------|-----------------------------------------------|
| **attachment**     | Attachment            | Document, File, Asset                          |
| **attachment_type**| Attachment Type       | Document Type, File Category                   |
| **category**       | Category              | Group, Class, Type, Collection                 |
| **currency**       | Currency              | Monetary Unit, Money Type                      |
| **footprint**      | Footprint             | Package, Form Factor, Physical Type            |
| **group**          | Group                 | Team, Department, Role                         |
| **label_profile**  | Label Profile         | Label Template, Print Template                 |
| **manufacturer**   | Manufacturer          | Brand, Vendor, Supplier, Maker                 |
| **measurement_unit**| Measurement Unit     | Unit of Measure, Unit, Measurement             |
| **parameter**      | Parameter             | Specification, Property, Attribute             |
| **part**           | Part                  | Component, Item, Product, Article, SKU         |
| **part_lot**       | Part Lot              | Stock Item, Inventory Item, Batch              |
| **project**        | Project               | Assembly, Build, Work Order                    |
| **storage_location**| Storage Location     | Warehouse, Bin, Location, Place                |
| **supplier**       | Supplier              | Vendor, Distributor, Reseller                  |
| **user**           | User                  | Member, Account, Person                        |

## How Synonyms Work

### Translation Mechanism

The synonym system works by integrating with Part-DB's translation system. When you define a synonym:

1. Part-DB creates translation placeholders for the element type
2. These placeholders are available in both capitalized and lowercase forms
3. The placeholders are used throughout the application where these terms appear

### Placeholder Format

Synonyms use special placeholders in translations:

- `[elementtype]` - Singular, lowercase (e.g., "part" → "item")
- `[Elementtype]` - Singular, capitalized (e.g., "Part" → "Item")
- `[[elementtype]]` - Plural, lowercase (e.g., "parts" → "items")
- `[[Elementtype]]` - Plural, capitalized (e.g., "Parts" → "Items")

### Language-Specific Synonyms

Synonyms are language-specific, meaning you can define different terms for different languages:

- English users see: "Component" and "Components"
- German users see: "Bauteil" and "Bauteile"
- French users see: "Composant" and "Composants"

This allows Part-DB to maintain proper multilingual support even with custom terminology.

## Use Cases and Examples

### Non-Electronics Inventory

**Scenario**: Using Part-DB for a library

**Synonyms**:
- Part → Book
- Category → Genre
- Manufacturer → Publisher
- Supplier → Distributor
- Storage Location → Shelf

**Result**: The interface now speaks library language: "Add a new Book", "Select a Genre", etc.

### Manufacturing Environment

**Scenario**: Managing production inventory

**Synonyms**:
- Part → Material
- Category → Material Type
- Part Lot → Batch
- Storage Location → Warehouse Zone
- Project → Assembly

**Result**: The interface uses manufacturing terminology: "Materials", "Batches", "Warehouse Zones", "Assemblies"

### Small Business Retail

**Scenario**: Managing store inventory

**Synonyms**:
- Part → Product
- Category → Department
- Manufacturer → Brand
- Supplier → Vendor
- Part Lot → Stock Item
- Storage Location → Store Location

**Result**: The interface matches retail terminology: "Products", "Departments", "Brands"

### Laboratory Setting

**Scenario**: Managing lab supplies and chemicals

**Synonyms**:
- Part → Reagent
- Category → Substance Type
- Manufacturer → Chemical Supplier
- Storage Location → Cabinet
- Part Lot → Bottle

**Result**: Lab-appropriate language: "Reagents", "Substance Types", "Cabinets"

### Educational Makerspace

**Scenario**: Managing shared tools and components

**Synonyms**:
- Part → Resource
- Category → Resource Type
- Storage Location → Area
- Project → Activity
- Part Lot → Available Unit

**Result**: Educational context: "Resources", "Resource Types", "Areas", "Activities"

## Managing Synonyms

### Editing Synonyms

To edit an existing synonym:
1. Find the synonym entry in the list
2. Modify the singular or plural form as needed
3. Click "Save" to apply changes

### Removing Synonyms

To remove a synonym:
1. Find the synonym entry in the list
2. Click the "Remove Entry" button (usually a trash icon)
3. Click "Save" to apply changes

After removal, Part-DB will revert to using the default term for that element type and language.

### Bulk Configuration

If you need to set up many synonyms at once (e.g., for a complete custom terminology set):

1. Define all your synonyms in the settings page
2. Each element type can have synonyms in multiple languages
3. Save once when all entries are configured

### Duplicate Prevention

The system prevents duplicate entries:
- You cannot have multiple synonyms for the same element type and language combination
- If you try to add a duplicate, you'll see a validation error
- Edit the existing entry instead of creating a new one

## Best Practices

### Consistency

- **Use consistent terminology**: If you change "Part" to "Product", consider changing "Part Lot" to "Product Item" or similar
- **Think holistically**: Consider how terms relate to each other in your domain
- **Test thoroughly**: Check various pages to ensure your terms make sense in context

### Singular and Plural Forms

- **Provide both forms**: Always define both singular and plural forms
- **Use proper grammar**: Ensure plurals are grammatically correct
- **Consider irregular plurals**: Some terms have non-standard plurals (e.g., "Box" → "Boxes", not "Boxs")

### Language Considerations

- **Match user expectations**: Use terms your users are familiar with in their language
- **Be culturally appropriate**: Some terms may have different connotations in different languages
- **Maintain professionalism**: Choose terms appropriate for your organizational context

### Planning Your Terminology

Before implementing synonyms:

1. **List all terms**: Identify which Part-DB terms don't fit your context
2. **Define replacements**: Decide on appropriate alternatives
3. **Check relationships**: Ensure related terms work together logically
4. **Get feedback**: Consult with users about proposed terminology
5. **Document decisions**: Keep a record of your synonym choices for future reference

## Limitations

### Not All Locations Covered

As an experimental feature, synonyms may not appear in:
- Some error messages
- Technical logs
- Email templates (depending on configuration)
- API responses
- Some administrative interfaces

The development team is working to expand synonym coverage.

### No Automatic Propagation

Synonyms only affect the user interface:
- Database values remain unchanged
- Export files use original terms
- API endpoints keep original names
- URLs and routes remain the same

### Performance Considerations

The synonym system:
- Caches translations for performance
- Minimal performance impact in normal usage
- Cache is automatically updated when synonyms change

## Technical Details

### Cache Management

Synonyms are cached for performance:
- Cache is automatically cleared when synonyms are saved
- No manual cache clearing needed
- Changes appear immediately after saving

### Translation Priority

When displaying text, Part-DB checks in this order:
1. Synonym (if defined for current language and element type)
2. Standard translation (from translation files)
3. Fallback to English default

### Environment Variables

Currently, synonyms can only be configured through the web interface. Future versions may support environment variable configuration.

## Troubleshooting

### Synonyms Not Appearing

**Problem**: You've configured synonyms but still see original terms.

**Solutions**:
- Clear your browser cache and reload the page
- Check that you've configured the synonym for the correct language
- Verify that you saved the settings after adding the synonym
- Remember this is an experimental feature - some locations may not be covered yet

### Inconsistent Terminology

**Problem**: Some pages show your synonym, others show the original term.

**Solutions**:
- This is expected behavior for the experimental feature
- Check if you've defined both singular and plural forms
- Report inconsistencies to help improve the system

### Wrong Language Displaying

**Problem**: Seeing synonyms from the wrong language.

**Solutions**:
- Check your user language preference in user settings
- Verify you've configured synonyms for the correct language code
- Ensure the language code matches exactly (e.g., "en" not "en_US")

### Synonyms Lost After Update

**Problem**: Synonyms disappeared after updating Part-DB.

**Solutions**:
- Check the settings page - they should still be there
- Database migrations preserve synonym settings
- If truly lost, restore from backup or reconfigure

## Future Enhancements

The synonym system is under active development. Planned improvements include:
- Coverage of more interface elements
- Synonym suggestions based on common use cases
- Import/export of synonym configurations
- Synonym templates for different industries
- More granular control over term usage

## Related Documentation

- [Getting Started]({% link usage/getting_started.md %}) - Initial Part-DB setup
- [Configuration]({% link configuration.md %}) - System configuration options
- [Concepts]({% link concepts.md %}) - Understanding Part-DB terminology

## Feedback

Since the synonym system is experimental, feedback is valuable:
- Report locations where synonyms don't appear
- Suggest new element types that should support synonyms
- Share your use cases to help improve the system
- Report bugs or unexpected behavior

You can provide feedback through:
- GitHub issues on the Part-DB repository
- Community forums and discussions
- Direct contact with the development team