Add a language and translate your storefront

A new language shows shoppers your storefront in the language they choose. First you turn the language on for your company. Then you translate what shoppers see: your storefront resources (products, categories, collections, pages, and so on), your navigation menus, your theme’s own strings, such as button labels, your agreements, and your product labels. The CLI reports what isn’t translated yet, machine-translates it, and writes it back. You review the result and finish when the report comes back empty.

Before you start

A Fluid API token for the company, from Settings > API Tokens, or your own sign-in with fluid login. The token needs these permissions:
- Languages update, to turn a language on.
- Storefront update, to translate storefront resources.
- Menus update, to translate navigation.
- Themes update, to save theme strings and to use machine translation.
- Agreements update, to translate agreements.
- Categories update, to translate product labels.
Know the language’s code, such as fr for French or zh-TW for Traditional Chinese. fluid translations languages lists every language Fluid supports and its code.
Install and sign in to the CLI:

npm install -g @fluid-app/fluid-cli @fluid-app/fluid-cli-localization
fluid login

Every fluid translations command prints JSON. Failures print a JSON error on stderr and exit with a non-zero code.

Prefer to answer questions? Run fluid translations walk in a terminal. It asks for the language, offers to turn it on, shows what’s missing, and machine-translates each type in batches. You accept, edit, or skip each translation, and each one is saved as you accept it. Type < to go back, > to skip, and ? for the menu.

Steps

Turn on the language

fluid translations enable fr --yes

This changes your company’s live configuration: shoppers can now choose French, and translations can be saved to it. The CLI asks for confirmation unless you pass --yes. If the language is already on, the output lists it under alreadyActive and nothing changes. You can turn on several at once, such as fluid translations enable fr de --yes.

Find what isn't translated

fluid translations missing fr

The report has one entry per type. Each entry gives total, missingCount, and a missing list. Every item in the list has an id and its source text in your default language. done is true only when every type is fully translated.Narrow the report with --type, for example --type products --type theme. Add --published-only to skip drafts, scheduled items, and archived items, which shoppers don’t see.

Machine-translate the gaps

Preview first. Without --write, nothing is saved:

fluid translations auto fr --limit 10

Then save the translations:

fluid translations auto fr --limit 25 --write --yes

--write changes live content. Theme strings publish to your storefront as soon as they’re saved. Machine translation uses Fluid AI and counts toward your company’s AI usage.--limit caps how many items of each type one run translates. Each type reports remaining, the number of items still left. Run the command again until remaining is 0 for every type. Machine translation fills text fields only. Set a per-language image or file in the next step.Each item is saved on its own. If the API refuses one, it’s listed under failed with the reason and the rest are saved; it counts toward remaining.

Review and correct translations

Compare an item’s default text with its translation:

fluid translations show products 60311 --lang fr

Then correct a translation or fill a field by hand:

fluid translations set products 60311 --lang fr --yes \
  --set title="Mélange de betteraves" \
  --set description="<p>Un concentré de betteraves pressé à froid.</p>"
fluid translations set menu-items 12/340 --lang fr --yes --set title="Boutique"
fluid translations set theme --lang fr --yes --set products.add_to_cart="Ajouter au panier"
fluid translations set labels 6 --lang fr --yes --set title="Végétalien"
fluid translations set agreements 4 --lang fr --yes --file terms-fr.json

Each set changes live content. A menu item’s id is <menu id>/<item id>, a theme string’s id is its dotted key, and a theme page string’s id is <template id>/<key>, exactly as the report prints them. For long or HTML values, such as an agreement’s text, put the fields in a JSON file and pass --file. An agreement’s title and text are saved together, so the first translation of an agreement needs both.

Confirm nothing is left

fluid translations missing fr --published-only

The language is fully translated when done is true. If anything is still missing, go back to the machine-translation step for those types, or set them by hand.

What gets translated

fluid translations types prints the same list.

Type	What it covers	Fields
`products`	Products	`title`, `introduction`, `description`, `feature_text`, `image_url`
`categories`	Categories	`title`, `description`, `image_url`
`collections`	Collections	`title`, `description`, `image_url`
`pages`	Pages	`title`, `description`, `image_url`
`posts`	Blog posts	`title`, `description`, `summary`, `image_url`
`media`	Media	`title`, `description`, `image_url`, `video_url`, `pdf_url`
`playlists`	Playlists	`title`, `description`, `image_url`
`enrollment-packs`	Enrollment packs	`title`, `description`
`menu-items`	Navigation menu items	`title`
`theme`	Your theme’s strings, in `locales/<iso>.json`	Every key in your default language’s locale file
`theme-sections`	Strings a page template keeps for itself, which take the place of the locale file’s strings on that page	Every key in the template’s source language
`agreements`	Agreements shoppers accept at checkout	`title`, `description`
`labels`	Product labels you created, such as “Vegan”	`title`

Machine translation fills the text fields. Images and files (image_url, video_url, pdf_url) keep showing the default-language file until you set a translated one.

What the status means

Report	What it means	What to do
A storefront item is in `missing`	It has no translation in this language yet. Shoppers see its default-language text.	Machine-translate it or set it by hand.
A menu item is in `missing`	Its title has no translation in this language.	Same as above.
A theme key is in `missing`	Your default locale file has the key, and the new language’s file lacks it or leaves it blank.	Same as above. Theme strings fall back to English until you translate them.
`skipped` on the theme entry	The theme has no locale file for the source language.	Pass `--from` with the language your theme’s strings are written in.
An agreement is in `missing`	Shoppers in this language see the agreement in your default language.	Machine-translate it or set it by hand. Have someone qualified review legal text.
A label is in `missing`	Its title in this language reads the same as in your default language.	Translate it. If the word is the same in both languages, such as a brand name, leave it out with `--skip labels:<id>`.
`sameAsSource` on the theme entry	Theme strings still word for word the source text.	Review them. Some are right as they are, such as a brand name.
`done: true`	Every type is translated.	Nothing.

A storefront item counts as translated once it has any translation in the language. If you translate only an item’s title, its other fields show the English text. Check those fields with show.

What isn’t covered

No command translates these, because Fluid has no API that translates them. Translate them in the admin, or leave them in your default language:

Promotions: their title, description, and terms.
Enrollment form fields and forms.
Fluid’s own product labels, “New” and “Trending”. Fluid translates them for you.
Theme settings written as plain text. A section setting typed straight into the page editor isn’t a translatable string yet. Use the page editor’s translate mode, which turns it into a key in your locale files; from then on, theme and theme-sections cover it.

Troubleshooting

“isn’t on for this company”. You tried to save to a language that’s off. Turn it on with fluid translations enable <iso> --yes.
A save returns 422. The language isn’t on for your company, or a field value isn’t valid. The error’s details name the field.
A save returns 403. Your token lacks the permission for that type. See Before you start. A theme page string returns 403 when its template is a shared or droplet template, which can’t be edited.
Machine translation fails or times out. Fluid AI is busy. Run the command again with a smaller --limit. Items that were already saved stay saved, and the report shows what’s left.
A theme save says the theme changed after it was read. Someone else saved the theme between the CLI’s read and its write, so the CLI saved nothing rather than overwrite their change. Run the command again.
Some items are listed under incomplete. The machine translation came back without one of their fields, even after asking again, so nothing was saved for them. Run the command again, or pass --skip <type>:<id>, such as --skip products:60311, to leave an item out and set it by hand.
A product change you didn’t expect. When you translate a product, any other field sent with the translation also changes the product. The CLI sends only translated fields. If you call the API directly, send only translated fields.

Use the API directly

The CLI wraps these operations, all authenticated with a Bearer token:

Configure company language turns a language on, and List company languages lists them.
The company list for each storefront resource, such as Company Products index, returns a languages array for every item. It names the languages the item is translated into.
The company update for each resource, such as Update a Product, saves a translation when you pass lang. Read Translate storefront resources for the rules.
Navigation menu items are translated through the menu API with lang. See Manage navigation menus.
Theme strings are the theme’s locale files. Updates a theme resource saves locales/<iso>.json. See Localization for how themes use them.
Theme page strings are a template’s translations. Updates a theme template saves them, replacing the whole object, so read the template first and merge.
Updates an agreement saves a translation when you pass language_iso. Retrieves an agreement in a language answers in your default language, and says so in its language_iso, when there is no translation yet.
Update Label saves a label’s title in the language you pass as lang.

curl -X PATCH "https://api.fluid.app/api/v202604/company/products/60311?lang=fr" \
  -H "Authorization: Bearer <your_token>" \
  -H "Content-Type: application/json" \
  -d '{"product": {"title": "Mélange de betteraves"}}'

Machine translation runs through Fluid AI, which has no published API reference yet. Use the CLI’s auto command for it.

Get started

Core concepts

Guides

Guided setup

Storefront guides

SDKs

Portal & Widgets

Add a language and translate your storefront

Before you start

Steps

What gets translated

What the status means

What isn’t covered

Troubleshooting

Use the API directly

​Before you start

​Steps

​What gets translated

​What the status means

​What isn’t covered

​Troubleshooting

​Use the API directly

Before you start

Steps

What gets translated

What the status means

What isn’t covered

Troubleshooting

Use the API directly