chill-bundles/docs/source/development/translation_directives.md

Translation Key Directives

These directives are meant to ensure better consistency across bundles, avoid duplication, and make keys more predictable.

General Principles

1. Use lowercase snake_case for all keys

2. Use dot-separated namespaces The dot is used to reflect:

   • bundle
   • feature
   • sub-feature
   • key type

3. Do not use spaces in keys

4. Avoid duplicating the same text in multiple places When a translation is needed, try a search for the translation value first and see if it exists elsewhere

5. If a key is used across multiple bundles, it must live in ChillMainBundle.

6. If a key is used across multiple bundles and is a generic term, it must be placed in the common namespace.

Key Structure

We use the following structure:

<scope>.<feature>.<sub-feature>.<key-type>

Where:

• <scope> identifies the bundle or shared context
• <feature> identifies the part of the module using the translation
• <element> describes the text purpose
• <subelement> for a multi-level element (e.g., activity.export.person.count.description)

Examples of scopes

• activity — ChillActivityBundle
• person — ChillPersonBundle
• common — neutral shared translation values

Naming Scopes

1. Bundle-specific keys

For most things inside a bundle:

activity.<feature>.<element>

Example:

activity.form.save
activity.list.title
activity.entity.type
activity.menu.activities
activity.controller.success_created

2. Shared UI elements (buttons, labels, generic text)

These belong in the common namespace in ChillMainBundle:

common.save
common.delete
common.edit
common.filter
common.duration_time

Translation Workflow

Use the following workflow when deciding where a key belongs:

1. Is this text used in more than one bundle? → Place in main or common

2. Is this text generic UI (button, label, pagination, yes/no)? → Place in common

3. Is this text specific to one bundle and one feature? → Place in <bundle>.feature.<element>

4. Is this text related to an entity or value object? → Place in <bundle>.entity.<entityname>.<field>

5. Is this text used in forms? → <bundle>.form.<field> or <bundle>.form.<action>

6. Is this text related to exports? → <bundle>.export.<feature>.<column>

7. Is it related to filtering, searching or parameters? → <bundle>.filter.<name> or → <bundle>.filter.<feature>.<field> for nested filters

Examples Based on Translations Within ChillActivityBundle

Below are concrete examples from ChillActivityBundle, refactored according to the guidelines.

General activity keys

Instead of scattered keys like:

Show the activity
Edit the activity
Activity
Duration time
...

We use:

activity.general.show
activity.general.edit
activity.general.title
activity.general.duration
activity.general.travel_time
activity.general.attendee
activity.general.remark
activity.general.no_comments

Forms

Instead of keys like:

Activity creation
Save activity
Reset form
Choose a type

Use:

activity.form.title_create
activity.form.save
activity.form.reset
activity.form.choose_type
activity.form.choose_duration

Long lists (like durations) should be grouped:

activity.form.duration.5min
activity.form.duration.10min
activity.form.duration.15min
activity.form.duration.1h
activity.form.duration.1h30
activity.form.duration.2h
...

Entities

Entity fields should follow:

activity.entity.activity.date
activity.entity.activity.comment
activity.entity.activity.deleted
activity.entity.location.name
activity.entity.location.type

Controller messages

Instead of strings as keys:

'Success : activity created!'
'The form is not valid. The activity has not been created !'

Use:

activity.controller.success_created
activity.controller.error_invalid_create
activity.controller.success_updated
activity.controller.error_invalid_update

Roles

Access control keys should be:

activity.role.create
activity.role.update
activity.role.see
activity.role.see_details
activity.role.delete
activity.role.stats
activity.role.list

Admin

activity.admin.configuration
activity.admin.types
activity.admin.reasons
activity.admin.reason_category
activity.admin.presence

CRUD

activity.crud.type.title_new
activity.crud.type.title_edit
activity.crud.presence.title_new

Activity Reason

activity.reason.list
activity.reason.create
activity.reason.active
activity.reason.category
activity.reason.entity_title

Exports

Group them logically:

activity.export.person.count.title
activity.export.person.count.description
activity.export.person.count.header

activity.export.period.sum_duration.title
activity.export.period.sum_duration.description
activity.export.period.sum_duration.header

Filters

Use hierarchical filters:

activity.filter.by_reason
activity.filter.by_type
activity.filter.by_date
activity.filter.by_location
activity.filter.by_sent_received
activity.filter.by_user

Aggregators

activity.aggregator.reason.by_category
activity.aggregator.reason.level
activity.aggregator.user.by_scope
activity.aggregator.user.by_job

Global/Shared Keys

Keys like the following must not be redeclared in each bundle:

• First name
• Last name
• Username
• ID
• Type
• Duration
• Comment
• Date
• Location
• Present / Not present
• Add / Edit / Delete / Save / Update

These belong in common or main:

common.firstname
common.lastname
common.username
common.id
common.type
common.comment
common.date
common.location
common.present
common.absent
common.add
common.edit
common.delete
common.save
common.update

Naming Directives Summary

• snake_case
• namespaced with dots
• bundle prefix for bundle-specific concepts
• common or main for shared concepts
• avoid free-floating keys (without namespace)
• reuse common keys wherever possible

Migration Strategy (Optional)

To apply this structure progressively:

1. New keys must follow these guidelines.
2. Existing keys may remain as-is until refactored.
3. When refactoring:
   • Move cross-bundle keys to ChillMainBundle and possible common namespace.
   • Replace duplicated keys with shared ones.

---

Avoiding Duplicate Translations

1. Use Shared Namespaces

Two namespaces must be used for shared translations:

• common.* — generic UI concepts (save, delete, date, name, etc.)

If a translation may be reused in multiple bundles, it must be placed in the common namespace or in ChillMainBundle.

2. Bundle-Specific Keys

Keys belonging only to one bundle or one feature are namespaced inside that bundle:

activity.<feature>.<element>
person.<feature>.<element>

3. Search Before Creating

Before adding a new translation key, developers must:

1. For common translations like "enregistrer/opslaan" look in the common namespace.
2. Search in Loco or translations for existing values.

If a suitable key exists, reuse it.

4. Only Create a New Key When Necessary

Create a new key only when the text is:

• specific to the bundle
• specific to the feature
• not reusable elsewhere

5. Progressive Cleanup

Old duplicates may remain temporarily. When updating code in an area, clean duplicate values by moving them into common or main.

General Workflow

• Reuse shared keys within common namespace.
• Search before creating new keys.
• Namespace bundle-specific keys under their bundle.
• Refactor progressively when touching old code.