Localization and Translation

Hyvä theme localization uses Magento's standard CSV translation dictionary system. The Hyvä Default Theme includes an English dictionary file (i18n/en_US.csv) containing all Hyvä-specific strings that are not part of core Magento. This file serves as the reference for translating Hyvä into other languages.

Translation Methods

There are two approaches to localizing a Hyvä theme:

Theme-Level Translation Dictionaries

Add a CSV translation dictionary file in your child theme's i18n/ directory, such as app/design/frontend/Vendor/ThemeName/i18n/de_DE.csv. This is the standard Magento approach and works the same way as with Luma-based themes.

Project-Level Language Packs

For projects requiring separation between Magento core translations, Hyvä translations, and project-specific translations, create a local language pack in app/i18n/{projectname}/{locale}/. This approach requires registration.php, language.xml, and one or more CSV translation files.

Thanks to Pieter Hoste from Baldwin for sharing this knowledge gem.

Creating a Project-Level Language Pack

The registration.php file looks like this, where {project} is a string like mysite and {locale} is a string like de_de:

<?php
use Magento\Framework\Component\ComponentRegistrar;
ComponentRegistrar::register(ComponentRegistrar::LANGUAGE, '{project}_{locale}', __DIR__);

The language.xml looks like this, where {locale} is a string like de_DE and {project} matches your project folder name:

<?xml version="1.0"?>
<language xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:noNamespaceSchemaLocation="urn:magento:framework:App/Language/package.xsd">
    <code>{locale}</code>
    <vendor>{project}</vendor>
    <package>{locale}</package>
</language>

For complete documentation, see the Adobe Commerce Localization Guide.

Pre-Built Hyvä Localization Modules

Hyvä provides pre-translated localization modules for many languages, available as Composer packages. These modules contain complete translations of all Hyvä-specific strings and can be installed alongside standard Magento language packs.

Available Languages

bg_BG (Bulgarian): hyva-themes/i18n-bg-bg
ca_ES (Catalan): hyva-themes/i18n-ca-es
da_DK (Danish): hyva-themes/i18n-da-dk
de_CH (Swiss German): hyva-themes/i18n-de-ch
de_DE (German): hyva-themes/i18n-de-de
es_ES (Spanish): hyva-themes/i18n-es-es
et_EE (Estonian): hyva-themes/i18n-et-ee
fr_FR (French): hyva-themes/i18n-fr-fr
it_IT (Italian): hyva-themes/i18n-it-it
ko_KR (Korean): hyva-themes/i18n-ko-kr
lt_LT (Lithuanian): hyva-themes/i18n-lt-lt
lv_LV (Latvian): hyva-themes/i18n-lv-lv
nl_BE (Belgian): hyva-themes/i18n-nl-be
nl_DI (Dutch, informal): hyva-themes/i18n-nl-di
nl_NL (Dutch): hyva-themes/i18n-nl-nl
pl_PL (Polish): hyva-themes/i18n-pl-pl
pt_BR (Brazilian Portuguese): hyva-themes/i18n-pt-br
ro_RO (Romanian): hyva-themes/i18n-ro-ro
uk_UA (Ukrainian): hyva-themes/i18n-uk-ua

Installing a Localization Module

Install a Hyvä localization module using Composer, then run Magento's setup:upgrade command. The following example installs the Italian localization:

composer require hyva-themes/i18n-it-it
bin/magento setup:upgrade

After installing the Hyvä localization module, complete the localization setup:

Install the corresponding Magento core language pack for the target locale
Configure the store view language in Stores → Configuration → General → Locale Options
Clear caches and deploy static content if in production mode