Translation Feature Guide

This guide shows how to set up and use the Translation Manager in Weaverse Studio to localize your storefront — reusable theme strings and page content — with AI auto-translation and a built-in review step.

Overview

Translation Manager localizes two kinds of content inside a Weaverse project:

Theme content: reusable storefront strings like button labels, empty states, and helper text (from your theme schema’s i18n.staticContent).
Page content: text and image content extracted from your page sections, blocks, and elements.

You author content once in your default language, then let the manager fan it out to every other language with one click — review, refine, and you’re done.

This is a different layer from the Hydrogen i18n loader (schema.server.ts / loadPage()), which controls how a published storefront reads translations at runtime. Use the i18n loader to wire locales into your theme (see Markets and Localization); use the Translation Manager to actually produce the translations.

Translation Manager open in Weaverse Studio

Core concept: Market vs. Language

Weaverse separates what region a page targets from what language it is read in. Understanding this split is the key to using the Translation Manager well.

Term	What it is	Example	Where it lives
Market	The country/region a page targets — the suffix of a Shopify locale	`vn`, `us`, `de`	One page layout per market
Language	The language the content is read in — a translation overlay on top of a market’s page	`vi`, `en`, `de`	Translation Manager

A market owns the page layout and the source content. Languages are overlays on that one layout. So a Vietnam market that sells in both Vietnamese and English is built once — you only translate the copy, you don’t rebuild the page per language.

One market layout with multiple language overlays

Legacy vs. market-first projects

How a project keys its content depends on when it was created:

Market-first projects (new) — content is keyed by market. One page per (market, type, handle), with language as a pure translation overlay. This is the model the Translation Manager is built for: edit once, translate everywhere.
Legacy projects (older) — content is keyed by full locale (vi-vn, en-vn, vi-us). Each language of the same country is a separate page you must author and maintain by hand, even when the layout is identical.

New projects are market-first automatically. Existing legacy projects keep working exactly as before — nothing breaks — but they do not get the “edit once, translate everywhere” benefit until they move to the market-first model.There is no automatic migration today. If you’re on a legacy project and want the market-first workflow, the recommended path is to create a new project (new projects are market-first by default) and rebuild your content there, or contact Weaverse support to discuss a migration. A self-serve in-Studio migration flow is on the roadmap.

Before You Start

Make sure these pieces are in place before your team starts translating:

You have installed @weaverse/hydrogen version ^5.16.3 or higher in your package.json.
Your project has a valid default locale configured.
The latest page content is published.
Your theme exposes reusable strings through schema.i18n.staticContent if you want to translate theme-level text, and sets i18n.translation: true.

Why this matters:

The first time Translation Manager opens, it auto-creates the default language from the project’s default locale.
Page scans read from the last published version of the project, not from unpublished editor changes.
Theme-level translation keys come from the theme schema, so they need to exist there before they can be synced and translated.

If the manager shows “Translation feature is not configured for this project,” your theme schema is missing i18n.translation: true. Add it (below) and reload Studio.

Theme Setup

If your project needs translatable theme strings, create a file (e.g. app/i18n/en.json) to store your keys:

{
  "cart": {
    "general": {
      "title": "Cart",
      "checkout": "Checkout"
    }
  },
  "general": {
    "search": {
      "placeholder": "Search"
    }
  }
}

Then import it into the theme schema under i18n.staticContent. You must also set i18n.translation: true to enable and display the Translation Manager in Studio.

import staticContent from '~/i18n/en.json'

export const schema = {
  i18n: {
    translation: true,
    staticContent,
  },
}

Recommended setup rules:

Keep keys structured in a multi-nested object format.
Use stable keys that describe the UI meaning, not the current copy.
Treat these default values as the source-language content for your project.

Editing theme strings from global theme settings

By default, i18n.staticContent keys are only editable inside the Translation Manager. If you want merchants to edit a specific string (or swap a per-language image) right from global theme settings, expose it with one of two dedicated input types:

Input type	Value it stores	Studio control
`translation-key`	A translatable string	Text input
`translation-image`	An image URL, translatable per language	Media picker

These input types require @weaverse/hydrogen 5.20.1 or higher (which ships @weaverse/schema 0.14.0). On earlier versions TypeScript rejects them with “Type 'translation-image' is not assignable to type InputType.”

The one rule that makes these different

For every other input type, name is the component prop that receives the value. For these two, name is a dot-notation key into i18n.staticContent — the same key you pass to t().

// Every other input: `name` is a prop
{ type: 'text', name: 'heading' }        // → props.heading

// Translation inputs: `name` is a content key
{ type: 'translation-key', name: 'cart.general.title' }   // → t('cart.general.title')

The consequence is important: values are stored per locale in the translation store, not in theme settings data. They never show up in your theme settings object or in component props — t() is the only way to read them back.

Declaring them in the theme schema

Add them to the theme schema’s settings array, which is a list of { group, inputs } groups:

import staticContent from '~/i18n/en.json'

export const schema = {
  i18n: {
    translation: true,
    staticContent,
  },
  settings: [
    {
      group: 'Cart',
      inputs: [
        {
          type: 'translation-key',
          name: 'cart.general.title',
          label: 'Cart title',
          helpText: 'Shown at the top of the cart drawer.',
        },
        {
          type: 'translation-key',
          name: 'cart.general.checkout',
          label: 'Checkout button',
        },
      ],
    },
  ],
}

Each name must match a key that already exists in your i18n.staticContent JSON — that file stays the source of truth for the default language.

Reading the values back

Exactly as you would any other theme string — with t():

import { useTranslation } from "@weaverse/hydrogen";

export function CartHeader() {
  const { t } = useTranslation();

  return (
    <div>
      <h2>{t("cart.general.title")}</h2>
      <button>{t("cart.general.checkout")}</button>
    </div>
  );
}

Per-language images

translation-image stores an image URL rather than a sentence, so a merchant can ship different artwork per language — a banner with baked-in text, a locale-specific badge, a regional payment logo. Alt text is not bundled in. Pair the image with its own translation-key input:

{
  group: 'Homepage promo',
  inputs: [
    {
      type: 'translation-image',
      name: 'promo.banner.image',
      label: 'Promo banner',
      helpText: 'Merchants can upload a different image per language.',
    },
    {
      type: 'translation-key',
      name: 'promo.banner.alt',
      label: 'Promo banner alt text',
    },
  ],
}

Both read back through the same t() lookup — the image one returns a URL string:

export function PromoBanner() {
  const { t } = useTranslation();

  return <img src={t("promo.banner.image")} alt={t("promo.banner.alt")} />;
}

Use these two input types in the theme schema’s settings only. They are not meant for component/section schemas — a section input’s name must be a real component prop, and these deliberately are not.

Reach for these when a string is worth surfacing to merchants without opening the Translation Manager — a promo headline, a shipping notice, a seasonal banner. For the long tail of UI strings, leave them in i18n.staticContent and translate them in the manager’s Theme scope.

The two content scopes

The manager splits everything translatable into two scopes, shown in the left navigation:

Scope	What it covers	Source
Theme	Reusable static UI strings shipped by the theme (button labels, empty states, helper text)	`i18n.staticContent`
Page	Content of each page/section — text and image content (headings, body copy, image alt)	Page items

Scope navigation in the Translation Manager

Open Translation Manager

In Studio, click the Advanced features icon in the topbar to open Translation Manager: Advanced features → Translation → Translation Manager

Advanced features icon in the Weaverse Studio topbar

On first open, the feature will:

Detect the project’s default locale.
Create the default language record if it does not exist yet.
Load the current language, theme content, and page content (a short initialization/scan runs once).

Add a Language

To add a translation target:

Click Add.
Search and pick the target language you want to support.

That’s it — the default language is always the source. The list is keyed by language, so markets that share a language share one set of translations; you never translate the same language twice. The default language and already-added languages appear disabled in the list.

If you open the manager on a storefront language you haven’t added yet, it prompts “Add this language?” so you can add it inline without losing context.

Languages available to add come from the locales published on your store (the same shopLocales your Hydrogen i18n config reads). To add a brand-new locale to your storefront routing first, see Markets and Localization.

Translate Theme Content

Use the Theme scope for project-wide UI strings. Default language mode (selected language = default):

Click Sync Theme Keys to import keys from schema.i18n.staticContent.
Edit the default values directly.
Changes save automatically.

Use this mode to clean up or rewrite the source copy before translating it. Translation mode (selected language ≠ default):

Open the Theme scope.
Review the source values on the left.
Click Auto-Translate to generate first-pass translations, or type translations on the right.
Refine any strings that need tone or brand adjustments. Edits save automatically.

Translate Page Content

Use the Page scope for page-specific content.

Switch to Page.
Pick the page you want to translate from the sidebar (untranslated counts are shown per group).
Choose Text Content or Image Content.
Edit translated values inline next to the source.
Use the Untranslated filter or search to focus on what’s missing.

Auto-Translate pages

Click Auto-Translate (the ✨ button in the toolbar). With the Page scope active, a page picker opens so you choose what to translate:

Select the current page to translate one page.
Select several pages or all pages to run a background translation job.
Track long-running jobs from the progress indicator — you can keep working while they run. The button is disabled for a language while its job is active, so you can’t double-submit.

Page translation edits save automatically as you work.

Bulk workflows: Import / Export

For large catalogs or external translation vendors, move translations in and out as files:

Export — download a page’s translations as CSV or JSON. CSV columns are Item ID, Key, Path, Original Value, Translated Value.
Import — upload a translated CSV or JSON back into a target language. Keep the export column shape so rows map to the right items.

Export → hand to a translator or your own pipeline → import. This is the recommended path when you need certified human translation rather than AI drafts.

How Translations Apply To The Project

The feature applies translations in two different ways:

Theme content: Stored as project translation keys. Use the useTranslation hook (below) in your frontend components so these strings render dynamically based on the active locale.
Page content: Stored separately from the main page JSON. Weaverse automatically applies these localized strings at runtime. You don’t need to add any code, hooks, or rendering logic to your Weaverse sections — Weaverse Hydrogen components automatically display the translated text when a non-default locale is requested.

Your source content stays intact, while each supported language gets its own translation layer applied on top.

Recommended Workflow

For the smoothest rollout, use this order:

Finalize the default-language content first.
Publish the latest page changes.
Sync theme keys.
Add the target language.
Auto-translate theme content.
Auto-translate page content.
Review high-visibility strings manually.
Preview the localized storefront and QA important flows.

Video walkthrough

Walkthrough video coming soon.

Troubleshooting

Manager not showing / “not configured”: the theme schema is missing i18n.translation: true. Add it and reload Studio.
A language I sell in isn’t listed: publish the locale in Shopify first; languages come from the store’s published locales. The manager will also prompt you to add a missing language when you open it on that locale.
Page edits don’t show on the live non-default site: make sure you edited the target language column (not the default) and that the row shows a saved state. On legacy (per-locale) projects, each locale is a separate page — see Legacy vs. market-first above.
Strings stay untranslated after Auto-Translate: re-run Auto-Translate for that page/language, or fill the remaining rows by hand. Use the Untranslated filter. Static keys not declared in i18n.staticContent won’t appear.
Static / theme keys missing: run Sync Theme Keys in the Theme scope, and confirm schema.i18n.staticContent exists.
Source language changed: use Re-sync Keys instead of recreating all translations.
Type '"translation-image"' is not assignable to type 'InputType': your installed @weaverse/schema predates these input types. Upgrade to @weaverse/hydrogen@5.20.1 or higher, which pins @weaverse/schema@0.14.0. Upgrading @weaverse/schema alone is not enough if @weaverse/hydrogen still pins an older version — check with npm ls @weaverse/schema.
A translation-key input shows nothing in Studio: its name must match a key that exists in i18n.staticContent. Unlike other inputs, name is a content key, not a component prop — a typo silently yields an empty field.

Limits & behavior

AI drafts, not final — always review. Translations preserve HTML tags, whitespace, and variables, and keep tone, but aren’t a substitute for human QA on high-visibility copy.
Background jobs — large auto-translate runs are queued and processed in the background; one active job per language at a time.
Provider — runs through the Weaverse AI proxy with automatic model failover, so a single provider outage doesn’t break a run. AI calls have cost, so prefer translating only the pages you changed.
Published content only — page scans read the last published version, not unpublished editor changes.

Rendering Translations in the Theme

To use translated theme content in your components, use the useTranslation hook from @weaverse/hydrogen. It connects to your theme’s static content and the localized strings managed in the Translation Manager.

Import the hook:

import { useTranslation } from "@weaverse/hydrogen";

Use the t function to render localized strings:

import { useTranslation } from "@weaverse/hydrogen";

export function CartSummary() {
  const { t } = useTranslation();

  return (
    <div>
      <h2>{t("cart.summary.orderSummary")}</h2>
      <button>{t("cart.actions.checkout")}</button>
    </div>
  );
}

Simple string interpolation: mark variables in your source JSON with double braces (e.g. {{name}}), then pass an object of variables as the second parameter to t:

app/i18n/en.json:

{
  "product": {
    "pictureOf": "Picture of {{name}}"
  }
}

React Component:

export function ProductImage({ name }: { name: string }) {
  const { t } = useTranslation();

  return <img alt={t("product.pictureOf", { name })} />;
}

Advanced: Pluralization with i18next

By default, the t function from useTranslation only supports simple string substitution (e.g., {{variable}}). It does not natively support advanced formatting like plurals. If your application requires plural forms or other advanced i18n features, configure an i18next instance and pass it as a custom translation function to Weaverse using the withWeaverse wrapper. For full step-by-step instructions, read the dedicated i18next Integration Guide.

Translating Shopify Content

Weaverse’s Translation Manager handles your storefront’s theme UI strings and custom page content. Your core catalog data (Products, Collections, Blogs, Articles, Menus) natively resides in Shopify. How to translate catalog data: localize your core Shopify catalog within the Shopify Admin using Shopify’s free Translate & Adapt app or any compatible 3rd-party translation app. How to query translated data: include the @inContext directive with the localized language and country codes in your GraphQL queries.

query Product(
  $handle: String!
  $language: LanguageCode
  $country: CountryCode
) @inContext(language: $language, country: $country) {
  product(handle: $handle) {
    title
    description
  }
}

When executing queries in your route loaders (context.storefront.query(...)), Hydrogen passes the correct language prefix automatically (e.g., /fr/products/hoodie), so Shopify returns translated strings natively and your Weaverse sections simply render product.title.

Programmatic access (coming)

Today every Translation Manager endpoint is authenticated by the Shopify shop session, so it’s only callable from inside Studio. A partner write-API (API-key auth for edit-once, AI-translate-everywhere automation from outside Studio) is being scoped.

Summary

Use Translation Manager to manage page content and reusable theme copy in one place. Author once in your default language, add target languages, auto-translate, review, and Weaverse applies the localized content at runtime. On market-first projects, you translate once per language and it serves every market that shares that language — so finalize your source content, then let the manager do the rest.

Markets and Localization — wiring locales into your Hydrogen theme.
Advanced Localization Guide — locale detection internals and the locale parameter.
i18next Integration Guide — pluralization and advanced formatting.

Environment

Building Components

Content Management

Internationalization

Security & Privacy

Pages & Routing

Advanced

Deployment

Translation Feature Guide

Translation Feature Guide

Overview

Core concept: Market vs. Language

Legacy vs. market-first projects

Before You Start

Theme Setup

Editing theme strings from global theme settings

The one rule that makes these different

Declaring them in the theme schema

Reading the values back

Per-language images

The two content scopes

Open Translation Manager

Add a Language

Translate Theme Content

Translate Page Content

Auto-Translate pages

Bulk workflows: Import / Export

How Translations Apply To The Project

Recommended Workflow

Video walkthrough

Troubleshooting

Limits & behavior

Rendering Translations in the Theme

Advanced: Pluralization with i18next

Translating Shopify Content

Programmatic access (coming)

Summary

​Translation Feature Guide

​Overview

​Core concept: Market vs. Language

​Legacy vs. market-first projects

​Before You Start

​Theme Setup

​Editing theme strings from global theme settings

​The one rule that makes these different

​Declaring them in the theme schema

​Reading the values back

​Per-language images

​The two content scopes

​Open Translation Manager

​Add a Language

​Translate Theme Content

​Translate Page Content

​Auto-Translate pages

​Bulk workflows: Import / Export

​How Translations Apply To The Project

​Recommended Workflow

​Video walkthrough

​Troubleshooting

​Limits & behavior

​Rendering Translations in the Theme

​Advanced: Pluralization with i18next

​Translating Shopify Content

​Programmatic access (coming)

​Summary

​Related

Translation Feature Guide

Overview

Core concept: Market vs. Language

Legacy vs. market-first projects

Before You Start

Theme Setup

Editing theme strings from global theme settings

The one rule that makes these different

Declaring them in the theme schema

Reading the values back

Per-language images

The two content scopes

Open Translation Manager

Add a Language

Translate Theme Content

Translate Page Content

Auto-Translate pages

Bulk workflows: Import / Export

How Translations Apply To The Project

Recommended Workflow

Video walkthrough

Troubleshooting

Limits & behavior

Rendering Translations in the Theme

Advanced: Pluralization with i18next

Translating Shopify Content

Programmatic access (coming)

Summary

Related