Skip to content

Managing Translations

Terug naar klant: Brekz

Translations are managed via brekz-cms language files in the /lang directory. Follow these conventions to ensure texts are available in both the Statamic Control Panel and the frontend (Blade/Vue).

🛑 CRITICAL: Production Safety First

PLEASE NOTE: If you are working on the live environment, always download the current production files first. Content editors (Brekz) may have updated translations directly in the CMS.

  • Backup Required: Create a backup of the existing language files before applying any changes.
  • Risk of Failure: Incorrect modifications or overwriting files without merging can cause missing text or broken interface elements on the live site.
  • Verify: Always double-check that your local version is in sync with the live environment before deploying.

1. Adding New Translations

To add a new string, locate the corresponding JSON file in /lang/{language}.json (e.g., nl.json).

  • Alphabetical Order: Always add new keys alphabetically within their groups to keep the files maintainable.
  • Structure: Keys are grouped by component or section.

Example: 

"cookieModal": {
    "analytical": "Analytisch",
    "functional": "Functioneel",
    "marketing": "Marketing",
    "test": "Hier een tekst"
}

2. Blade vs. Vue (Placeholders)

There is a critical difference in how placeholders (dynamic variables) are handled between PHP (Blade) and JavaScript (Vue).

Blade (PHP): Uses a colon prefix: :query

Vue (JS): Uses curly brackets: {query}

⚠️ Dual-use strings: If a translation is needed in both environments, create two separate keys to ensure the placeholders work correctly:

Example:

Blade.php: 

"orderBefore_blade": "Order within :query for fastest delivery",
Vue.js: 
"orderBefore_vue": "Order within {query} for fastest delivery"

3. Implementation in Blade (.php)

Setup

If you are creating a new translation group (e.g., cookieModal), you must first create a corresponding PHP file in /lang/nl/cookieModal.php to make it accessible to Blade. Use the following boilerplate:

<?php
return $translations['cookieModal'] ?? [];

Usage

Standard:

{{ __("cookieModal.test") }}

With HTML:

Use the unescaped syntax if the translation contains HTML tags: 

{!! __("cart.emptyCartBlock.text") !!}

With Placeholders:

Pass an array to fill the :colon placeholders: 

{{ __("brands.allBrands", ['title' => 'hondenvoer']) }}

4. Implementation in Vue (.vue)

In Vue components, no extra file setup is required. The strings are globally available via the $t helper.

Standard:

```javascript {{ $t("cookieModal.test") }} 

#### With HTML:

  You must use the `v-html` directive to render HTML tags correctly:
  ```javascript
    <label
        for="sub-subchoice-1"
        v-html="$t('NewsletterUnsubscribe.frequencySettings.allBenefits')"
    >
    </label>
   ```
#### With Placeholders:
  Use an object to pass dynamic values to the `{bracket}` placeholders:
```javascript
{{
    $t('header.account.welkom', {
        name: authStore.authenticatedUser?.name,
    });
}}