Multi-Language Font Weight Implementation Options #261

chrisfalaska · 2025-09-24T16:56:04Z

chrisfalaska
Sep 24, 2025
Maintainer

Multi-Language Font Weight Implementation Options

Prepared by: Chris Freddberg
Prepared on: 09/04/2025
Reviewed on: 09/04/2025
Reviewed by: Auro Engineering, Brandon Shields
Outcome: Option 2

Problem Statement

Our current typography system uses consistent font-weight values across all languages, but visual weight differences between AS Circular and an i18n font such as Noto Sans JP require different actual weights to achieve visual consistency:

AS Circular (English): Uses weight 450 for optimal appearance
Noto Sans JP (Japanese): Requires weight 400 to match AS Circular 450 visually

We need to implement a solution that maintains design consistency while supporting mixed-language content.

Option 1: CSS Custom Properties with Language Attributes

Implementation

:root {
  /* Default English weights (AS Circular) */
  --wcss-heading-xs-weight-en: 450;
  --wcss-body-weight-en: 450;
  
  /* Japanese weights (Noto Sans JP) */
  --wcss-heading-xs-weight-jp: 400;
  --wcss-body-weight-jp: 400;
  
  /* Set defaults */
  --wcss-heading-xs-weight: var(--wcss-heading-xs-weight-en);
  --wcss-body-weight: var(--wcss-body-weight-en);
}

/* Japanese language overrides */
:lang(ja) {
  --wcss-heading-xs-weight: var(--wcss-heading-xs-weight-jp);
  --wcss-body-weight: var(--wcss-body-weight-jp);
}

HTML Requirements

<h3 class="heading-xs">English Heading</h3>
<h3 class="heading-xs" lang="ja">日本語のタイトル</h3>

Or document-level:

<html lang="ja">
  <h3 class="heading-xs">All content uses Japanese weights</h3>
</html>

Pros

Explicit weight declarations (400 maps to 400, etc)
Easy to understand and maintain
Leverages existing CSS custom properties architecture
Scales well for additional languages

Cons

Requires lang attributes on HTML elements
Mixed-language content needs careful markup
Document-level lang affects all content uniformly

Best For

Single-language pages
Teams comfortable managing lang attributes

Option 2: Font-Face Weight Mapping ⭐️ Recommended

Re-maps font-weights in the @font-face declarations.

Implementation

/* 
  IMPORTANT: Japanese weight mapping
  
  Due to visual weight differences between EN fonts and Noto Sans JP,
  we map EN weights to visually consistent Noto Sans JP weights.
  
  Weight mapping table:
  - AS Circular 300 → Noto Sans JP 300
  - AS Circular 450 → Noto Sans JP 400  ← Creates mapping below
  - AS Circular 500 → Noto Sans JP 500
*/

Original Japanese font declarations:

@font-face {
  font-family: "Noto Sans JP";
  font-weight: 400;
  src: url("noto-jp-400.woff2") format("woff2");
  unicode-range: U+3040-309F, U+30A0-30FF, U+4E00-9FAF, U+FF66-FF9F;
}

Updated weight mapping for visual consistency:

@font-face {
  font-family: "Noto Sans JP";
  font-weight: 450; /* Maps 450 to 400 weight file */
  src: url("noto-jp-400.woff2") format("woff2");
  unicode-range: U+3040-309F, U+30A0-30FF, U+4E00-9FAF, U+FF66-FF9F;
}

HTML Requirements

No special markup needed:

<h1 class="heading-xs">Alaska Airlines 日本便</h1>

"Alaska Airlines" → AS Circular 450
"日本便" → Noto Sans JP 400 (via mapping)

Pros

Character-based: Works at individual character level
Automatic: No HTML changes or language attributes required
Precise: Each script gets appropriate font weight
Mixed-content friendly: Handles multilingual text seamlessly
Maintains existing architecture: No changes to CSS classes or variables
Clear documentation addresses maintenance concerns
Intentional mapping is explicitly explained
Weight table provides quick reference for developers
Comments and documentation will be stripped during minification

Cons

Documentation concern: font-weight: 450 displays as weight 400 for Japanese
Debugging complexity: Declared weight doesn't match visual weight
New developers might not understand the mapping
Requires discipline to maintain documentation (although fonts should rarely change)

Best For

Mixed-language content
Minimal code changes required
Automatic font selection based on Unicode ranges
Documentation and maintainability
Scalability with multiple developers

Option 3: Language-Specific CSS Files

Implementation Structure

alaska.global.css          // Base styles (no font weights)
alaska.global.en.css      // English-specific font weights
alaska.global.jp.css       // Japanese-specific font weights
alaska.global.ko.css      // Korean-specific font weights, etc

Base CSS (alaska.global.css)

All typography styles WITHOUT font-weight declarations:

.heading-xs {
  font-family: var(--wcss-heading-xs-family);
  letter-spacing: var(--wcss-heading-xs-letter-spacing);
  /* font-weight defined in language-specific files */
  line-height: var(--wcss-heading-xs-line-height);
  font-size: var(--wcss-heading-xs-font-size);
}

English CSS (alaska.global.en.css)

:root {
  --wcss-heading-xs-family: "AS Circular";
  --wcss-heading-xs-weight: 450;
  --wcss-heading-lg-weight: 300;
}

/* Apply weights */
.heading-xs { font-weight: var(--wcss-heading-xs-weight); }
.heading-lg { font-weight: var(--wcss-heading-lg-weight); }

Japanese CSS (alaska.global.jp.css)

:root {
  --wcss-heading-xs-family: "Noto Sans JP";
  --wcss-heading-xs-weight: 400;
  --wcss-heading-lg-weight: 300;
}

/* Apply weights */
.heading-xs { font-weight: var(--wcss-heading-xs-weight); }
.heading-lg { font-weight: var(--wcss-heading-lg-weight); }

HTML Implementation

Server-side or build-time language detection:

<link rel="stylesheet" href="alaska.global.css">
<link rel="stylesheet" href="alaska.global.{{ language }}.css">

OR conditional loading:

<link rel="stylesheet" href="alaska.global.css">
{% if language == 'jp' %}
  <link rel="stylesheet" href="alaska.global.jp.css">
{% elif language == 'en' %}
  <link rel="stylesheet" href="alaska.global.en.css">
{% endif %}

Build Process Integration

WCSS:

const language = TARGET_LANGUAGE || 'en';
const cssFiles = [
  'alaska.global.css',
  `alaska.global.${language}.css`
];

Pros

Clear boundaries between language-specific styles
No hidden mappings or documentation concerns
Only load CSS for target language
Easy to add new languages
Each file has single responsibility
Each page targets one primary language
Smaller CSS payload per language

Cons

Requires build system integration
More files to maintain
Needs server-side or build-time language determination
Cannot handle multilingual content on same page

Best For

Separate sites/subdomains per language (alaskaair.com/jp/, alaskaair.com/ko/)
Pages that are one language
Static site generation with language variants / build time localization

Comparison Matrix

Criteria	Option 1 (CSS Variables)	⭐ Option 2 (Documented Mapping)	Option 3 (Language Files)
Implementation Complexity	Medium	Low	Medium
HTML Changes Required	Yes	No	No*
Mixed-Language Support	Limited	Excellent	Poor
Performance Impact	None	None	Optimized
Maintainability	Good	Excellent	Excellent
Documentation Clarity	Excellent	Excellent	Excellent
Browser Support	Excellent	Excellent	Excellent
Debugging Ease	Easy	Easy	Very Easy
Build System Integration	None	None	Required
Scalability (New Languages)	Good	Good	Excellent
Character-Level Font Selection	No	Yes	No
Page-Level Language Flexibility	Good	Excellent	Single Language Only

*Option 3 requires explicit language classes for mixed content

Recommendations

⭐ For Mixed-Language Content: Option 2 - Well-Documented Font-Face Mapping

If pages contain mixed English and Japanese text within the same elements:

✅ Works automatically with mixed-language content at character level
✅ Requires no HTML or JavaScript changes
✅ Addresses documentation concerns with clear comments
✅ Maintains existing CSS architecture
✅ Provides clear weight mapping reference

For Single-Language Sites with Build Systems: Option 3 - Language-Specific CSS Files

If pages have separate language versions and can implement build-time language detection:

✅ No hidden font-weight mappings
✅ Load only what you need
✅ Clear separation of concerns
✅ Scalable: Easy to add languages and unique typography rules

Decision Matrix:

Do you have mixed-language content? → Use Option 2
Can you implement build-time language detection? → Consider Option 3
Can you reliably add lang attributes? → Consider Option 1
Do you need minimal implementation complexity? → Use Option 2
Is performance optimization critical? → Consider Option 3 (single-language) or Option 2 (mixed-content)

Performance

Key takeaways

Computational cost is primarily in the initial character matching rather than ongoing processing.
Each font subset with a unicode-range requires a separate HTTP request.
The browser needs to parse and evaluate unicode-range declarations to determine which font files to load, adding minimal computational overhead.
File sizes can be reduced through sub-setting: Instead of loading a 2MB font with all characters, you might load only a 200KB subset with JP characters, significantly improving initial page load.
Browsers only download font subsets when they encounter characters in that range, reducing unnecessary downloads.
Smaller, focused font files cache more efficiently.

Resources

Next Steps

Phase 1: Implement Option 2 for immediate functionality
Phase 2: Add comprehensive documentation and developer guidelines
Phase 3: Launch

Navigation Menu

Uh oh!

Multi-Language Font Weight Implementation Options #261

Uh oh!

{{title}}

Uh oh!

Replies: 0 comments

Select a reply

Uh oh!

Uh oh!

Multi-Language Font Weight Implementation Options #261

Uh oh!

chrisfalaska Sep 24, 2025 Maintainer

Multi-Language Font Weight Implementation Options

Problem Statement

Option 1: CSS Custom Properties with Language Attributes

Implementation

HTML Requirements

Pros

Cons

Best For

Option 2: Font-Face Weight Mapping ⭐️ Recommended

Implementation

HTML Requirements

Pros

Cons

Best For

Option 3: Language-Specific CSS Files

Implementation Structure

Base CSS (alaska.global.css)

English CSS (alaska.global.en.css)

Japanese CSS (alaska.global.jp.css)

HTML Implementation

Build Process Integration

Pros

Cons

Best For

Comparison Matrix

Recommendations

⭐ For Mixed-Language Content: Option 2 - Well-Documented Font-Face Mapping

For Single-Language Sites with Build Systems: Option 3 - Language-Specific CSS Files

Decision Matrix:

Performance

Key takeaways

Resources

Next Steps

Replies: 0 comments

chrisfalaska
Sep 24, 2025
Maintainer