> ## Documentation Index
> Fetch the complete documentation index at: https://varaahi.vritservicespro.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Localization guide

> Add a language, translate the theme, and extend VARAHI to a new locale — with the file structure and key conventions.

# Localization guide

The practical version of [International](https://varaahi.vritservicespro.com/features/international.md). Read this when you
are adding a language or translating the theme yourself.

***

## File structure

```text theme={"system"}
locales/
`-- en.default.json      Source strings - never translate this
|-- fr.json
|-- de.json
`-- es.json
```

Each file is a flat JSON object of key — string.

```json theme={"system"}
{
  "general": {
    "cart": "Cart",
    "menu": "Menu",
    "search": "Search"
  },
  "cart": {
    "in_cart_one": "%{count} item in cart",
    "in_cart_other": "%{count} items in cart",
    "empty": "Cart is empty"
  },
  "accessibility": {
    "open_cart": "Open cart",
    "open_menu": "Open menu"
  }
}
```

***

## Key conventions

| Convention | Meaning |
| - | - |
| `namespace.topic` | Grouping. `general`, `product`, `cart`, `header`, `footer`, `accessibility` |
| `_one` / `_other` suffix | Plural forms. Shopify picks based on `cart.item_count` |
| `%{count}` | The interpolated number |
| `accessibility.*` | Screen-reader labels. Always write these — they are the least visible and the most important |

> [!NOTE]
>
> The `accessibility` namespace holds every `aria-label` in the theme. A merchant who
> translates the visible strings but not these ends up with a page where a
> screen-reader user hears English button names. It is the most commonly missed part
> of a translation.

***

## Adding a language

**1. Create the language in Shopify**

**Settings → Languages → Add language**. Pick the language and the domain it
will be served on.

**2. Create the locale file**

Copy `locales/en.default.json` to `locales/<code>.json` — for example
`locales/fr.json`.

**3. Translate every value**

Keep the keys identical. Change only the values.

**4. Push the theme**

```bash theme={"system"}
shopify theme push --store your-store.myshopify.com
```

Shopify copies the theme's locale files into the new language.

**5. Copy the locale in the admin**

**Settings → Languages → your language — Actions → Copy from default theme**.
This picks up any keys added since the theme was first published.

**6. Verify the language selector**

It appears in the header automatically once the second language is published.

***

## Using a translation in Liquid

```liquid theme={"system"}
{%- comment -%} Simple {%- endcomment -%}
{{ 'general.cart' | t }}

{%- comment -%} With a placeholder {%- endcomment -%}
{{ 'cart.in_cart_other' | t: count: cart.item_count }}

{%- comment -%} In an attribute {%- endcomment -%}
<button aria-label="{{ 'accessibility.open_cart' | t }}">…</button>

{%- comment -%} In JavaScript, via a data attribute {%- endcomment -%}
<button
  data-announcement-empty="{{ 'cart.empty' | t }}"
  data-announcement-one="{{ 'cart.in_cart_one' | t }}"
  data-announcement-other="{{ 'cart.in_cart_other' | t }}"
>
```

***

## Right-to-left languages

The theme's layout uses logical CSS properties and flexbox, so RTL mirrors
automatically. The header, the cart drawer and the mobile drawer all slide in from
the correct edge.

> [!WARNING]
>
> Directional icons need an RTL variant. If you add a chevron that points "forward",
> add `.icon--rtl { transform: scaleX(-1); }` and apply it inside an
> `[dir="rtl"]` selector.

***

## Regional formats

| Thing | Handled by |
| - | - |
| Date format | Shopify's `date` filter, using the storefront locale |
| Number format | Shopify's money filter, using the storefront locale |
| Currency symbol and position | **Settings → Markets** |
| Address formats | Shopify's markets settings |
| Phone number format | **Settings → Markets** |

> [!NOTE]
>
> Only the strings in `locales/` are yours to translate. Formats are Shopify's job,
> and they follow the storefront locale automatically.

***

## Adding a language in code

If you deploy with the CLI, the flow is:

```bash theme={"system"}
# 1. Create the locale file
cp locales/en.default.json locales/fr.json

# 2. Translate it (any editor, any tooling)

# 3. Push
shopify theme push --store your-store.myshopify.com

# 4. In the admin, copy the locale from the default theme
```

> [!WARNING]
>
> After every theme update, re-copy the locale in **Settings → Languages**. New keys
> added by the update are not present in your existing translated files, and they will
> silently fall back to English.

***

> **[International](https://varaahi.vritservicespro.com/features/international.md)**
>
> The feature overview.

> **[Code reference](https://varaahi.vritservicespro.com/going-further/code-reference.md)**
>
> The full file map.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.