# How Archify Supports Localization for the Viewer UI: Embedded JSON Architecture

> Archify enables viewer UI localization by embedding i18n JSON into HTML. Access translations at runtime with the global Archify.i18n() helper. Learn more about this architecture.

- Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify)
- Tags: internals
- Published: 2026-08-29

---

**Archify implements viewer UI localization by embedding a self-contained i18n JSON payload directly into every generated HTML page, exposing a global `Archify.i18n()` helper that resolves translation keys at runtime.**

The tt-a1i/archify repository provides a lightweight, zero-dependency internationalization system for static viewer outputs. By bundling translation data directly within the HTML template, Archify enables complete localization for the viewer UI without requiring external resource files or build-step transformations.

## Embedding the i18n Payload in HTML

Archify stores all translation data inside a dedicated `<script>` element with the ID **`archify-i18n-data`**. This element contains a JSON object declaring the active **`locale`** (e.g., `"en"`) and a **`messages`** map keyed by semantic identifiers such as `viewer.kind.frontend` and `viewer.theme.toggle.title`.

In [`examples/web-app.html`](https://github.com/tt-a1i/archify/blob/main/examples/web-app.html) at line 4964, the payload appears as:

```html
<script id="archify-i18n-data" type="application/json">
{
  "locale": "en",
  "messages": {
    "viewer.kind.frontend": "Frontend",
    "viewer.kind.backend": "Backend",
    "viewer.theme.toggle.title": "Toggle theme (T)",
    "viewer.theme.toggle": "Toggle color theme",
    "viewer.motion.live": "Live"
  }
}
</script>

```

This embedding strategy ensures the translation context is available immediately upon page parse, eliminating network requests for language files.

## Runtime Initialization and Global State

Early in the page lifecycle, the Archify runtime extracts and parses the i18n payload to initialize the global state. This occurs in the core template logic found in [`archify/assets/template.html`](https://github.com/tt-a1i/archify/blob/main/archify/assets/template.html) and demonstrated in [`examples/web-app.html`](https://github.com/tt-a1i/archify/blob/main/examples/web-app.html) around line 5466:

```js
const archifyI18nData = JSON.parse(
  document.getElementById('archify-i18n-data').textContent
);
Archify.locale = archifyI18nData.locale || 'en';

```

By assigning the locale to the global `Archify` object before any UI components render, the system establishes the language context for all subsequent translation lookups.

## Translation Lookup API

The viewer accesses localized strings through a minimal API exposed on the global `Archify` object. UI components request text using semantic keys from the `messages` map, and the helper returns the corresponding string for the active `locale`:

```js
const txt = Archify.i18n('viewer.theme.toggle.title');
// Returns "Toggle theme (T)" for the default English locale

```

This indirection decouples the component code from specific languages, allowing the same HTML template to render correctly for any locale simply by swapping the JSON payload.

## Implementing Custom Locales

To localize the viewer UI for a different language, replace the content of the `archify-i18n-data` script with a new `locale` value and corresponding `messages`. The following example configures French translations:

```html
<script id="archify-i18n-data" type="application/json">
{
  "locale": "fr",
  "messages": {
    "viewer.kind.frontend": "Frontend",
    "viewer.kind.backend": "Backend",
    "viewer.theme.toggle.title": "Basculer le thème (T)",
    "viewer.theme.toggle": "Basculer le thème couleur",
    "viewer.motion.live": "En direct"
  }
}
</script>

```

When the page loads, the viewer automatically displays French strings without any changes to the underlying JavaScript.

## Dynamic Locale Switching

For advanced use cases requiring runtime language changes, you can replace the JSON payload and re-initialize the i18n system without reloading the page:

```js
function switchLocale(newLocaleData) {
  const script = document.getElementById('archify-i18n-data');
  script.textContent = JSON.stringify(newLocaleData);
  
  // Re-initialize the i18n system
  const data = JSON.parse(script.textContent);
  Archify.locale = data.locale;
  Archify.messages = data.messages;
  
  // Trigger UI refresh to update rendered components
}

```

This approach updates `Archify.locale` and the message registry, causing subsequent calls to `Archify.i18n()` to return strings in the new language.

## Core Implementation Files

The Archify localization system spans several key files in the repository:

- **[`archify/assets/template.html`](https://github.com/tt-a1i/archify/blob/main/archify/assets/template.html)** – Contains the core template logic that reads the `archify-i18n-data` script element and exposes the `Archify.locale` property and translation helper.
- **[`examples/web-app.html`](https://github.com/tt-a1i/archify/blob/main/examples/web-app.html)** – Demonstrates the embedded i18n JSON structure and runtime locale assignment at lines 4964 and 5466.
- **[`archify/examples/web-app-rendered.html`](https://github.com/tt-a1i/archify/blob/main/archify/examples/web-app-rendered.html)** – A fully rendered output showing the viewer UI with localized strings in action.
- **[`examples/checkout-platform-delta.html`](https://github.com/tt-a1i/archify/blob/main/examples/checkout-platform-delta.html)** – Additional concrete example embedding the i18n payload and setting the locale for specific viewer instances.

## Summary

- Archify embeds viewer UI translations in a `<script id="archify-i18n-data">` element containing a JSON object with `locale` and `messages` properties.
- The runtime parses this blob during initialization to set `Archify.locale` and populate the global message registry.
- UI components retrieve localized text via `Archify.i18n(key)`, decoupling display logic from language-specific data.
- Supporting new languages requires only swapping the JSON payload inside the HTML template, with no modifications needed to the core viewer code in [`archify/assets/template.html`](https://github.com/tt-a1i/archify/blob/main/archify/assets/template.html).

## Frequently Asked Questions

### Where does Archify store translation data for the viewer UI?

Archify stores all translation data inside a `<script>` element with the ID `archify-i18n-data`, embedded directly in each generated HTML page. This element contains a JSON object specifying the `locale` and a `messages` map keyed by semantic identifiers.

### How do I add a new language to the Archify viewer?

Replace the content of the `archify-i18n-data` script element with a JSON object containing your target `locale` string (e.g., `"fr"`) and a corresponding `messages` object mapping translation keys to localized strings. The viewer will automatically use the new language on the next page load.

### What function does Archify use to resolve translation keys?

The global `Archify.i18n()` function accepts a translation key string (such as `'viewer.theme.toggle.title'`) and returns the localized string matching the current `Archify.locale` from the embedded `messages` map.

### Can the viewer UI language be changed without reloading the page?

Yes, you can implement runtime switching by updating the `textContent` of the `archify-i18n-data` script element with new locale data, then re-parsing it to update `Archify.locale` and `Archify.messages`. This requires manually triggering a UI refresh to re-render components with the new translations.