# Archify Locale Support: English and Chinese Internationalization Implementation

> Discover Archify's built-in locale support for English and Chinese. Learn how it implements internationalization with localStorage and URL overrides.

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

---

**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`](https://github.com/tt-a1i/archify/blob/main/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:

```javascript
// 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:

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

```

### Switching Locales Programmatically

Update the interface language and persist the choice:

```javascript
// 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:

```javascript
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`](https://github.com/tt-a1i/archify/blob/main/viewer/semantic-lens.js):

```javascript
// 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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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.