Multilanguage

KahunaCart's catalog lives in a database rather than in files, so it carries its own translations instead of using Grav's per-file ones. This page covers what can be translated, how a translation resolves, and how to edit translations from the admin, the API or a catalog file.

Before you begin

• Grav's system.languages.supported lists the languages the site runs in.
• Migration 0012_translations has been applied, either by auto-migrate or by bin/plugin kahunacart migrate.
• ext-intl is installed, if you want locale-aware price formatting. Without it, Money::format() falls back to USD 28.00 in every language.

Turn on the multilanguage catalog

1. Add the languages to user/config/system.yaml:

   YAMLCopy

   languages:
    supported: [en, de]
   

2. Run bin/grav clearcache.

3. Run bin/plugin kahunacart migrate if your store does not auto-migrate.

4. Translate a product from the admin, or PATCH one through the API.

5. Visit /de/shop.

The storefront now serves a German catalog at /de/shop and falls back to the base text for anything untranslated.

To turn it back off, remove supported and clear the cache. The storefront returns to base text everywhere. The translation rows stay in the database and come back the moment the language does.

What can be translated

What is not translated

How translations are stored

One table, added by migration 0012_translations:

kahunacart_translations(entity_type, entity_id, language, field) -> value

It has a unique key over those four columns and an index on (entity_type, language, entity_id). Writes are upserted on the unique key through the portable Dialect::upsert(). Reads are batched by entity type, so a page of twenty-five products costs one extra SELECT.

There are no foreign keys, so every deletion path sweeps its own translations: ProductRepository::deleteWithVariants(), ProductOptionRepository::deleteOption(), CategoryRepository::deleteReparenting() and the shipping and tax deleteForZone() methods.

A missing row is the fallback. Clearing a field in the admin deletes its row, and an empty string is never written.

How translations resolve

KahunaCart::activeLanguage() decides the active catalog language. It returns Grav's own $grav['language']->getLanguage() when languages are enabled, and null otherwise. null means "this store has no languages", which is what makes the single-language path a no-op.

The fallback chain is active language → site default language → the base columns on the row. The base columns are not a language, so they are not in the chain.

Resolution is per field, not per entity. A product with a German title and no German summary renders the German title and the English summary.

Routing

Grav strips the language prefix from the request path before any plugin sees it, so by the time KahunaCart matches its routes, $uri->path() reads /shop/product/foo whichever language was asked for. The plugin therefore keeps two answers to "where does the storefront live":

The prefix comes from Grav's own getLanguageURLPrefix(). A site that runs its default language without a prefix (include_default_lang: false) gets /shop for the default and /de/shop for the rest.

Formatting

Prices are formatted in the active language's locale everywhere they render: the plugin's templates, the kahunacart_price() Twig function and filter, and the JSON payload the option picker swaps prices from. /en prints $28.00; /de prints 28,00 $.

The locale comes from I18n\Locales::forLanguage(), which canonicalizes and stops: de-CH becomes de_CH, and de stays de. A bare language code is a valid ICU locale, so de and de_DE both print 58,00 €. Grav's own override_locale derivation is not used, because it produces non-locales such as en_EN and ja_JA.

SEO

On a product or category page the plugin emits:

• a canonical URL carrying the language prefix, so each translation points at itself rather than at the English original;
• JSON-LD with inLanguage on the Product and the BreadcrumbList, and with the translated name, description and breadcrumb names;
• og:locale, plus the translated og:title and og:description.

inLanguage is omitted entirely on a single-language site rather than guessed at.

Sitemap

With grav-plugin-sitemap installed, every storefront URL is contributed once per configured language, each carrying hreflang alternates naming all the others:

<url>
  <loc>https://example.com/de/shop/product/reef-runner-tee</loc>
  <xhtml:link rel="alternate" hreflang="en" href="https://example.com/en/shop/product/reef-runner-tee" />
  <xhtml:link rel="alternate" hreflang="de" href="https://example.com/de/shop/product/reef-runner-tee" />
  <lastmod>2026-08-18</lastmod>
</url>

This is the same treatment the sitemap plugin gives ordinary pages when multilang_enabled is on, which is its default. Verified against sitemap 5.2.2.

Every language gets an entry whether or not the product has been translated into it. The store's own multilang_enabled setting is not consulted for these URLs.

Search

Search on /de matches the German text and the base columns. Without both, a store part-way through translating its catalog would have products that are visible on /de and cannot be found from the /de search box.

The translated match is an EXISTS against kahunacart_translations in the same query, so a product whose title, summary and description all match still comes back once, with no second query.

Orders and email

An order records the language it was shopped in, in kahunacart_orders.language. The storefront stamps it on every cart write, so a customer who switches language mid-cart sees the totals relabel. Completion freezes it.

NULL covers every order placed before this migration and every order on a single-language store. It means "the site's default", and the readers treat it that way.

Three things read the column:

• The calculator. The shipping and tax stages translate their labels against the order's language, not the request's. A webhook completing an order and a merchant recalculating one from an English admin both produce the customer's words.
• The cart. A line item's title is snapshotted in the cart's language, then frozen.
• The queued emails. Order confirmation, payment received, shipped, refunded and abandoned-cart emails all render inside the order's language: subject line, both templates and the money formatting.

A queue drained from cron has no request, no URL and no session, so I18n\RenderLanguage sets the active language for each render and restores the previous one afterwards.

Translate a product in the admin

1. Open the product in the admin and go to the Details panel.
2. Click the language tab you want, next to Base (en).
3. Enter the overrides. Each field shows the base text as its placeholder, and a "falls back to the base" note when it is empty.
4. Click Save.

A dot on a tab means that language carries at least one override, so you can see what has been translated without opening every tab. Saving an empty field removes the override; it never stores an empty string.

Categories get the same switcher in their inline editor. Option axes get one switcher per axis, covering the axis name and every one of its value labels in a single Save translations click.

Shipping methods and tax rates get a row of per-language label inputs inside their existing editors. Their row ids change on every save, so the overrides ride through the form and are posted back with the save.

Translate through the API

Every catalog GET carries a translations map, unresolved:

{
  "id": 11,
  "title": "Reef Runner Tee",
  "translations": {
    "de": { "title": "Riffläufer-Shirt", "summary": "Ein Baumwollshirt" }
  }
}

The map is unresolved so that an editor can tell a field that is falling back from one that is translated.

POST and PATCH accept the same key, following the category_ids rule: absent means leave them alone; present means these are the overrides now. A language missing from the map is dropped, and a field sent empty inside a language clears that one override.

curl -X PATCH .../api/kahunacart/products/11 \
  -H 'Content-Type: application/json' \
  -d '{"translations": {"de": {"title": "Riffläufer-Shirt"}}}'

The same contract applies on /kahunacart/categories/{id}, /kahunacart/tags/{id}, /kahunacart/products/{id}/options/{optionId}, /kahunacart/products/{id}/options/{optionId}/values/{valueId}, and, inside each method or rate object, on /kahunacart/shipping/zones/{id} and /kahunacart/tax/zones/{id}.

GET /kahunacart/config reports languages and default_language, which is what the admin reads to decide whether to draw a switcher at all.

Export and import translations

bin/plugin kahunacart export writes translations into the catalog file, and import reads them back:

products:
  - slug: reef-runner-tee
    title: Reef Runner Tee
    translations:
      de:
        title: Riffläufer-Shirt
        summary: Ein Baumwollshirt
    options:
      - name: Colour
        translations:
          de:
            name: Farbe
        values:
          - label: Navy
            color: '#1f3a5f'
            translations:
              de:
                label: Marineblau
          - Sand

A value with nothing but a label still exports as a bare string, so values: [S, M, L] reads as the list it is.

Two rules govern the file:

• It records overrides, not resolved text. Exporting resolved text would turn a fallback into a translation the moment the file was re-imported.
• Import is a merge, not a sync. A language the file names is written; a language it does not name is left as it is. This is not the API's replace-wholesale rule: a German file must not silently delete a store's French.

A translations: block naming a field nobody translates fails validation by name, before anything is written.

What a theme needs

Nothing, if the theme uses the plugin's Twig helpers. kahunacart_products(), kahunacart_product() and kahunacart_categories() return rows already resolved for the active language, kahunacart_price() formats in the active locale, and kahunacart_base_route() returns the language-prefixed route.

Two things a theme author may want to add:

• A language switcher in the site header. Grav has the pieces (grav.language.getLanguages, grav.language.getActive, page.url), but the plugin does not draw one.
• <html lang="…">. Most themes already emit it from grav.language.getActive. If yours hardcodes en, a German page claims to be English.

Related

• Storefront — routes, templates and Twig functions
• Theming — custom properties and the class reference
• Products and catalog — the catalog the translations sit on