README

Simple package to integrate Vue translations into Pimcore.

Dependencies

Release	Supported Pimcore Versions	Supported Symfony Versions	Branch
1.x	`11.0`	`6.2`	main

Installation

You can install the package via composer:

composer require ntriga/pimcore-vue-translations

Add Bundle to bundles.php:

return [
    Ntriga\PimcoreVueTranslations\PimcoreVueTranslationsBundle::class => ['all' => true],
];

Usage

Getting the translations

Inject translations into your Twig template to preload them for your Vue app. The package provides the pimcore_translations twig function that fetches the translation messages for a given language. When Pimcore shared translation fallbacks are configured, the package resolves that fallback chain and merges missing values into the requested locale before returning the payload. For example, in your layout template add:

<!DOCTYPE html>
<html>
<head>
    <meta charset="UTF-8">
    <title>Your App</title>
    {# Other head elements #}
</head>
<body>
    <div id="app"></div>

    <script>
      // Preload the translations and current locale.
      window.__TRANSLATIONS__ = {{ pimcore_translations(app.locale)|json_encode()|raw }};
      window.__LOCALE__ = '{{ app.locale }}';
    </script>
    <script src="/build/app.js"></script>
</body>
</html>

Vue

Configure your Vue i18n (or other vue translation package) instance with the preloaded translations. For example:

import axios from 'axios';
import { createI18n } from 'vue-i18n';

// Use the translations and locale injected by Twig.
const messages = window.__TRANSLATIONS__ || { en: {} };
const locale = window.__LOCALE__ || 'en';

const i18n = createI18n({
    locale,
    fallbackLocale: 'en',
    messages,
});

export default i18n;

If your Pimcore system config contains a fallback like en_GB: en_BE, calling pimcore_translations('en_GB') will return an en_GB catalogue that already contains en_BE values for keys that are empty in en_GB.

Registering missing translation keys

The package provides an endpoint where you can send a single, or multiple translatation keys to to register them in the Pimcore shared translations.

To make the route available in your application, add the following in config/routes/vue-translations.yaml:

pimcore_vue_translations:
    resource: '@PimcoreVueTranslationsBundle/Controller/'
    type: attribute
    prefix: /translations-api

After that is done, integrate a missing key handler. Example with i18n:

import { createI18n } from "vue-i18n";
import axios from "axios";
import { debounce } from "lodash";

const messages = window.__TRANSLATIONS__ || { en: {} };
const currentLocale = window.__LOCALE__ || "en";

const missingKeys = new Set();
const reportedKeys = new Set();

const sendMissingKeys = debounce(() => {
    if (missingKeys.size > 0) {
        const keys = Array.from(missingKeys);
        axios
            .post("/translations-api/register-missing-translations", {
                keys,
                locale: currentLocale, // Consider using the actual current locale if it can change dynamically
            })
            .catch((error) =>
                console.error("Error registering missing keys:", error)
            );
        missingKeys.clear();
    }
}, 1000);

const handleMissingTranslation = (locale, key) => {
    if (!reportedKeys.has(key)) {
        console.warn(
            `Missing translation key: "${key}" for locale "${locale}"`
        );
        reportedKeys.add(key);
        missingKeys.add(key);
        sendMissingKeys();
    }
    // Fallback: return the key itself if no translation is found
    return key;
};

const i18n = createI18n({
    legacy: false,
    locale: currentLocale,
    fallbackLocale: "en",
    messages,
    missing: handleMissingTranslation,
});

export function setLocale(locale) {
    i18n.global.locale = locale;
}

export default i18n;

New translation keys are registered for all configured Pimcore valid languages, so the shared translation row is ready to be filled in from the admin UI.

Changelog

Please see CHANGELOG for more information on what has changed recently.

Credits

All contributors

License

GNU General Public License version 3 (GPLv3). Please see License File for more information.

ntriga / pimcore-vue-translations

Maintainers

Package info

Statistics

Security