Archify Locale Support: English and Chinese Internationalization Implementation

Archify provides built-in locale support for English (en) and Simplified Chinese (zh), implementing a minimal internationalization layer through centralized language management with localStorage persistence and URL parameter overrides.

Archify offers a streamlined approach to internationalization designed for reliability and ease of use. The repository handles locale support through a dedicated module that normalizes input, manages persistence, and ensures consistent language experiences across the application. This guide examines the technical implementation, API methods, and configuration options available in the tt-a1i/archify codebase.

Supported Locales and Language Codes

Archify officially supports two locale codes:

• en – English (default interface language)
• zh – Simplified Chinese interface translation

The system validates all locale inputs against these specific values. Any language code outside of 'en' or 'zh' is normalized to null and discarded by the normalize function, ensuring only supported locales propagate through the application.

How Archify Handles Locale Management

Centralized Language Module

All locale functionality is encapsulated in the ArchifySiteLanguage module located at docs/assets/site-language.js. This singleton pattern provides consistent read/write operations across the application, preventing fragmentation of locale logic.

The module exposes two primary methods for locale interaction:

// Retrieve current locale (returns 'en' or 'zh')
const currentLocale = ArchifySiteLanguage.read();

// Persist a new locale (only accepts 'en' or 'zh')
ArchifySiteLanguage.write('zh');

Input Normalization and Validation

The normalize function within the language module enforces strict input validation. When ArchifySiteLanguage.write() receives a locale string, it passes through normalization that:

1. Accepts only exact matches 'en' or 'zh'
2. Treats all other values as null
3. Discards invalid inputs without throwing errors

This defensive programming approach prevents corrupted locale states from propagating through the UI rendering layer.

Persistence and Storage Mechanisms

Selected languages persist across sessions using localStorage under the key archify-lang. The implementation maintains backward compatibility by recognizing legacy storage keys from previous versions.

When ArchifySiteLanguage.write('zh') executes:

1. The value normalizes to 'zh'
2. The system stores the code in localStorage.setItem('archify-lang', 'zh')
3. Subsequent calls to ArchifySiteLanguage.read() retrieve the persisted value

If no stored value exists, the system defaults to English ('en') without requiring explicit initialization.

URL Parameter Override

Archify supports temporary locale switching via the lang query parameter. When a user navigates to:

https://example.com/?lang=zh

The consumeRequestedLanguage function processes the parameter during page load:

1. Extracts the lang value from the URL
2. Persists it via ArchifySiteLanguage.write()
3. Removes the parameter from the address bar using history.replaceState()
4. Applies the locale immediately to the interface

This approach enables shareable links with predetermined language settings while maintaining clean URLs after consumption.

Implementing Locale-Aware Features

Reading Current Locale Settings

Access the active locale anywhere in the application:

const locale = ArchifySiteLanguage.read();
console.log(`Current language: ${locale}`); // Outputs: 'en' or 'zh'

Switching Locales Programmatically

Update the interface language and persist the choice:

// Switch to Chinese interface
ArchifySiteLanguage.write('zh');

// Verify persistence
console.log(ArchifySiteLanguage.read()); // 'zh'

Localized String Lookup Pattern

Implement UI translations using the locale as a dictionary key:

function getLabel(key) {
  const labels = {
    en: { welcome: 'Welcome', save: 'Save' },
    zh: { welcome: '欢迎', save: '保存' },
  };
  
  const locale = ArchifySiteLanguage.read();
  return labels[locale][key] || labels['en'][key]; // Fallback to English
}

Locale-Aware String Comparison

For sorting or comparing strings according to locale-specific rules, Archify utilizes localeCompare in viewer/semantic-lens.js:

// Example from viewer/semantic-lens.js
items.sort((a, b) => a.label.localeCompare(b.label, ArchifySiteLanguage.read()));

Fallback Behavior and Default Settings

When the locale system initializes, it follows a deterministic fallback chain:

1. URL Parameter – Check for ?lang= override (highest priority)
2. localStorage – Retrieve archify-lang value if present
3. Default – Fallback to 'en' if no valid source found

This hierarchy ensures that temporary URL-based language sharing takes precedence over stored preferences, while maintaining English as the reliable baseline for all users.

Summary

• Archify supports exactly two locales: English (en) and Simplified Chinese (zh)
• Locale management lives in docs/assets/site-language.js via the ArchifySiteLanguage module
• Storage uses localStorage with the key archify-lang and maintains legacy compatibility
• URL parameter ?lang= enables temporary locale overrides that persist after consumption
• Invalid locale codes normalize to null, causing automatic fallback to English
• The system defaults to English when no valid locale source exists

Frequently Asked Questions

What languages does Archify support?

Archify officially supports English and Simplified Chinese, identified by the locale codes en and zh respectively. The system does not support regional variants (such as en-US or zh-TW) or additional languages beyond these two options.

How does Archify store the selected language?

The framework stores locale preferences in the browser's localStorage under the key archify-lang. When users select a language, ArchifySiteLanguage.write() persists the value, making it available across browser sessions without server-side storage requirements.

Can I set the language via URL parameters?

Yes. Appending ?lang=zh or ?lang=en to any Archify URL temporarily sets the locale. The consumeRequestedLanguage function processes this parameter during page load, stores the preference, and removes the parameter from the visible URL while maintaining the selected language.

What happens if an unsupported language code is provided?

The normalize function in docs/assets/site-language.js filters all inputs against the supported list. Any value other than 'en' or 'zh' returns null, causing the system to discard the input and fallback to English. This prevents invalid locale states from breaking the interface rendering.

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