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

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 at line 4964, the payload appears as:

<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 and demonstrated in examples/web-app.html around line 5466:

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:

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:

<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:

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 – 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 – Demonstrates the embedded i18n JSON structure and runtime locale assignment at lines 4964 and 5466.
• archify/examples/web-app-rendered.html – A fully rendered output showing the viewer UI with localized strings in action.
• 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.

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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}