Skip to main content
Helium’s localization system lets you translate your paywall’s text into any language, preview territory-specific pricing, and manage translations at scale — with AI auto-translation, manual editing, and third-party sync via Localizely. Localization in Helium has two distinct layers: copy (translated UI text) and pricing (territory-specific product prices and currencies). They work independently — you can localize copy without changing pricing territory, and vice versa.

​
How It Works

Every paywall has a localizations file that maps translation keys to per-locale values. At runtime, the SDK provides the user’s preferred languages, and Helium resolves the best available translation using a waterfall:
  1. Exact locale match (e.g., es-MX)
  2. Base language match (e.g., es from es-MX)
  3. Universal fallback (the key — your source language)
  4. Inline fallback

​
Translation Keys

Translation keys are identifiers that connect your UI code to translated values. They originate from your paywall.

​
How keys are created

  • Automatic extraction — When you create a paywall, Helium’s AI analyzes your App.tsx and wraps localizable strings in translate() calls, generating stable keys.
  • Manual — You can add translate(“my_key”, “fallback”) calls directly in your code.
  • From the translation editor — Add keys through the localization UI and reference them in code.

​
Key format

Keys are plain strings, typically snake_case: hero_title, cta_subscribe, feature_list_item_1. Auto-generated keys may include a hash suffix for uniqueness (e.g., unlock_premium_a3f2b1).

​
Managing Translations

The localization editor is a sidebar/modal in the paywall editor with a full set of tools:

​
AI Auto-Translation

Helium can auto-translate all keys to any supported locale using an LLM:
  1. Select a target locale (or translate to all added languages at once).
  2. Helium sends the source values plus any translation context you’ve provided.
  3. The AI returns translations, which are marked with status helium.
  4. You can review and edit any auto-translated value — editing changes the status to user.
Auto-translation is powered by Gemini and processes up to 100 keys per batch. It uses your source locale (typically English) as the input. AI is also used during paywall creation — when you create a paywall from scratch or a template, Helium can automatically identify localizable strings in your code, wrap them in translate() calls, and generate the initial localizations. You can also simply prompt the editor to localize your paywall into whatever language is necessary!

​
Localizely Integration

For teams with existing translation workflows, Helium integrates with Localizely (a translation management platform):
  • Sync overrides — Localizely translations can override Helium values per key and locale.
  • Status tracking — Values from Localizely are marked with status localizely and can be locked to prevent accidental edits.
  • Key linking — Map Helium translation keys to Localizely keys.
  • Filter — Filter the translation table to show only Localizely-managed or non-Localizely keys.

​
Translation Metadata

Every translation value tracks its source status: Metadata is stored per key, per locale — so one key might have base for English, helium for Spanish, and user for German (if you manually corrected the AI’s output).

​
Territory and Pricing

Territory controls product pricing. Locale controls UI text. These are separate concepts:
  • Locale — Determines which translation values to display (e.g., es shows Spanish copy).
  • Territory — Determines which price points to display (e.g., USA shows USD prices, JPN shows JPY).

​
How pricing localization works

  1. Each product has price points per territory (from App Store Connect, Google Play, or Stripe).
  2. When you select a territory in the editor, Helium resolves the correct price, currency, and currency symbol for that territory.
  3. The products.tsx file is regenerated with localized pricing data.
  4. Your paywall accesses prices through product data — never hardcode price strings.

​
Territory picker

The editor’s context panel includes a territory selector. Changing it:
  • Updates all product prices to that territory’s pricing.
  • Updates offer eligibility (intro offers may vary by territory).
  • Validates that the territory is available for the selected platform (iOS and Android use different territory code formats).
The default territory is USA. If a product doesn’t have pricing for the selected territory, Helium falls back to the closest available territory.

​
Previewing Locales in the Editor

The paywall editor has a locale selector that lets you preview any language in real time:
  1. Select a locale from the dropdown (e.g., es, de, ja).
  2. The editor sends the locale and translations to the preview iframe via postMessage.
  3. The LocalizationProvider re-renders the paywall with the selected locale’s translations.
  4. You see exactly what a Spanish-speaking user (or German, Japanese, etc.) would see — with the correct copy and formatting.
Changes made in the translation editor are reflected in the preview immediately, without saving.

​
Locale-Specific Experiments

Separate from UI localization, Helium supports per-locale experiments at the workflow level. A workflow can run different A/B tests for different locales — for example, testing annual pricing in en users while testing monthly pricing for es users. This is configured through the workflow’s locale-experiment mappings, not through the paywall’s localization system. See [Experiments] and [Workflows] for details.

​
SDK Runtime Behavior

When a paywall loads in your app:
  1. The SDK provides heliumContext.locale.preferredLanguages — the user’s device language preferences (e.g., [“es-MX”, “es”, “en”]).
  2. The paywall’s LocalizationProvider receives this and resolves translations using the waterfall (exact locale → base language → fallback).
  3. Product prices are resolved based on the user’s territory (separate from language), using heliumContext.locale.currentCurrency and related fields.
This means a user in Mexico with their phone set to Spanish sees:
  • Copy in es-MX (or es if no Mexico-specific translations exist)
  • Prices in MXN from the Mexico App Store territory

​
Key Rules

  • The "" (empty string) locale is the universal fallback — always populate it with your source language values.
  • Translation keys must match between App.tsx and localizations.ts — use the unused key cleanup to keep them in sync.
  • Don’t hardcode prices in your UI text — use product data from products.tsx. Hardcoded prices will block publishing.
  • Territory and locale are independent — a user can have Spanish copy with USD pricing (e.g., a Spanish speaker in the US).
  • AI translations are a starting point — always review auto-translated values for quality, especially for marketing copy.
  • Each translation value tracks its source status (base, helium, user, localizely) for auditability.
  • Locale-specific experiments are a workflow-level feature, not a paywall-level feature.

​
Common Patterns