bubble-icon

Translations

GraphCommerces uses Linqui for interface translations. This guide provides an introduction to how translations work in your graphCommerce app and how to add support for a language of your choosing.

How translations work

All available interface translations are stored as .po files in the /locales directory.

Example of /locales/es.po

...

msgid "Your cart is empty"
msgstr "Su carrito está vacío"

msgid "Your session is expired"
msgstr "Su sesión ha caducado"

msgid "canceled"
msgstr "cancelado"

The msgid is the message being translated. In /node_modules/@graphcommerce/magento-cart/components/EmptyCart/EmptyCart.tsx, you can see a the first msgid is passed as a propped, wrapped in the <Trans> component:

<FullPageMessage
  title={<Trans>Your cart is empty</Trans>}
  ...
>

Customize translations

In /locales/en.po, find the msgid Your cart is empty and change the msgstr:

msgid "Your cart is empty"
msgstr "Empty cart!"

Refresh to see your changes updated

Make changes to translations

Make changes to translations. Refresh to see changes updated.

Adding translations to custom component

If you're building a component, you can wrap the strings you want to translate in the <Trans> jsx macro:

<Typography variant='h3'>
  <Trans>Call us now</Trans>
</Typography>

Add Linqui to the component's imports:

import { t, Trans } from '@lingui/macro'

Run yarn lingui. All new (missing) translations will be added to translations files:

//Example terminal output

┌─────────────┬─────────────┬─────────┐
LanguageTotal count │ Missing├─────────────┼─────────────┼─────────┤
en (source)208-│ nl          │     2081│ es          │     2081└─────────────┴─────────────┴─────────┘

Edit the translations files to add your translation:

//Example from /locales/es.po

...

msgid "Call us now"
msgstr ""

Passing {values} to translations

You can pass values in msgid's:

<PageMeta
  title={t`Cart (${data?.cart?.total_quantity ?? 0})`}
  ...
/>

The syntax in the translation files:

//Example from /locales/en.po

...

msgid "Cart"
msgstr "Cart"

msgid "Cart ({0})"
msgstr "Cart ({0})"

Adding a new language

  1. Create a new storeview and configure the locale, Admin > Store > Configuration > General > General > Locale. Choose one of the options from the Magento Locale codes (below).

  2. In your .env file, add the desired route and store_code to the NEXT_PUBLIC_LOCALE_STORES environment variable. The route will be visible to the user (added to the url) when the user switches storeview.

    It's considered best practice to match the route with the locale code, replacing an underscore for a dash. For example, to add Swedish (Finland), which has locale code sv_FI, add the following:

//Example from .env

NEXT_PUBLIC_LOCALE_STORES =
  '{"en-us":"default",sv-fi":"[store_code from desired storeview]"}'
  1. Run yarn lingui:
//Example terminal output

┌─────────────┬─────────────┬─────────┐
LanguageTotal count │ Missing├─────────────┼─────────────┼─────────┤
en (source)208-│ sv          │     208208└─────────────┴─────────────┴─────────┘
  1. A new .po translation file will be generated in the /locales directory, the filename matching the object key or, in case a locale code is used, matching the charactes before the dash (which represent the language).

    In the example above, the filename would result in sv.po:

//Example from /locales/sv.po

msgid ""
msgstr ""
"POT-Creation-Date: 2022-03-30 14:45+0200\n"
"MIME-Version: 1.0\n"
"Content-Type: text/plain; charset=utf-8\n"
"Content-Transfer-Encoding: 8bit\n"
"X-Generator: @lingui/cli\n"
"Language: sv\n"

msgid "<0>{name}</0> has been added to your shopping cart!"
msgstr ""

msgid "Above <0/>"
msgstr ""

msgid "Account"
msgstr ""

  1. Add your translations ins the newly created .po file. Run the app and use the store switcher to navigate to your new storeview. Github copilot ↗ provides very accurate suggestions in VS Code with the Github copilot extention ↗.

Magento Locale codes

LocaleLanguage (country)
af_ZAAfrikaans (South Africa)
sq_ALAlbanian (Albania)
ar_DZArabic (Algeria)
ar_EGArabic (Egypt)
ar_KWArabic (Kuwait)
ar_MAArabic (Morocco)
ar_SAArabic (Saudi Arabia)
az_Latn_AZAzerbaijani (Latijns, Azerbaijan)
bn_BDBangla (Bangladesh)
eu_ESBasque (Spain)
be_BYBelarusian (Belarus)
bs_Latn_BABosnian (Latijns, Bosnia & Herzegovina)
bg_BGBulgarian (Bulgaria)
ca_ESCatalan (Spain)
zh_Hant_HKChinese (traditioneel Chinees, Hong Kong SAR China)
zh_Hant_TWChinese (traditioneel Chinees, Taiwan)
zh_Hans_CNChinese (vereenvoudigd Chinees, China)
hr_HRCroatian (Croatia)
cs_CZCzech (Czechia)
da_DKDanish (Denmark)
nl_BEDutch (Belgium)
nl_NLDutch (Netherlands)
en_AUEnglish (Australia)
en_CAEnglish (Canada)
en_IEEnglish (Ireland)
en_NZEnglish (New Zealand)
en_GBEnglish (United Kingdom)
en_USEnglish (United States)
et_EEEstonian (Estonia)
fil_PHFilipino (Philippines)
fi_FIFinnish (Finland)
fr_BEFrench (Belgium)
fr_CAFrench (Canada)
fr_FRFrench (France)
fr_LUFrench (Luxembourg)
fr_CHFrench (Switzerland)
gl_ESGalician (Spain)
ka_GEGeorgian (Georgia)
de_ATGerman (Austria)
de_DEGerman (Germany)
de_LUGerman (Luxembourg)
de_CHGerman (Switzerland)
el_GRGreek (Greece)
gu_INGujarati (India)
he_ILHebrew (Israel)
hi_INHindi (India)
hu_HUHungarian (Hungary)
is_ISIcelandic (Iceland)
id_IDIndonesian (Indonesia)
it_ITItalian (Italy)
it_CHItalian (Switzerland)
ja_JPJapanese (Japan)
km_KHKhmer (Cambodia)
ko_KRKorean (South Korea)
lo_LALao (Laos)
lv_LVLatvian (Latvia)
lt_LTLithuanian (Lithuania)
mk_MKMacedonian (North Macedonia)
ms_MYMalay (Malaysia)
nb_NONorwegian Bokmål (Norway)
nn_NONorwegian Nynorsk (Norway)
fa_IRPersian (Iran)
pl_PLPolish (Poland)
pt_BRPortuguese (Brazil)
pt_PTPortuguese (Portugal)
ro_RORomanian (Romania)
ru_RURussian (Russia)
sr_Cyrl_RSSerbian (Cyrillisch, Serbia)
sr_Latn_RSSerbian (Latijns, Serbia)
sk_SKSlovak (Slovakia)
sl_SISlovenian (Slovenia)
es_ARSpanish (Argentina)
es_BOSpanish (Bolivia)
es_CLSpanish (Chile)
es_COSpanish (Colombia)
es_CRSpanish (Costa Rica)
es_MXSpanish (Mexico)
es_PASpanish (Panama)
es_PESpanish (Peru)
es_ESSpanish (Spain)
es_USSpanish (United States)
es_VESpanish (Venezuela)
sw_KESwahili (Kenya)
sv_FISwedish (Finland)
sv_SESwedish (Sweden)
th_THThai (Thailand)
tr_TRTurkish (Turkey)
uk_UAUkrainian (Ukraine)
vi_VNVietnamese (Vietnam)
cy_GBWelsh (United Kingdom)

Next steps