Building a Scalable i18n System in Nuxt 3

Creating an internationalized (i18n) system in Nuxt 3 that scales effectively is crucial for websites aiming to support multiple languages. This approach not only ensures that new languages can be added effortlessly but also maintains optimal SEO performance.

The Challenge of Traditional i18n

A common method to add a new language might involve a quick configuration in nuxt-i18n, followed by deploying machine-translated JSON files. While this can be done rapidly, it often leads to incomplete translations. Pages may generate hreflang tags pointing to non-existent translations, affecting search engine rankings.

A Data-Driven Solution

At BulkPicTools, each tool is defined with a JSON file containing language-specific keys. Instead of managing separate configuration files or deployment flags, the presence of a language key in the JSON acts as a readiness signal:

{
  "slug": "image-compressor",
  "category": "compress",
  "icon": "lucide:file-zip",
  "en": {
    "name": "Image Compressor",
    "meta": { "title": "...", "description": "..." },
    "hero": { "scene": "Drag in a photo, get back a smaller one." }
  },
  "zh": {
    "name": "图片压缩",
    "meta": { "title": "...", "description": "..." },
    "hero": { "scene": "拖入图片，输出更小的文件。" }
  }
}

Add a ja key when the Japanese translation is ready, and it's automatically supported.

Centralizing Language Configuration

Nuxt's configuration file serves as the central registry for supported languages:

// nuxt.config.ts
i18n: {
  locales: [
    { code: 'en', language: 'en', file: 'en.json' },
    { code: 'zh', language: 'zh-CN', file: 'zh.json' },
    { code: 'ja', language: 'ja', file: 'ja.json' },
  ],
  defaultLocale: 'en',
  strategy: 'prefix_except_default',
}

For future expansions, simply add a new locale entry.

Resolving hreflang Issues

To ensure hreflang tags only link to available translations, a filtering function is employed. This function refines the hreflang links based on available language support for each page, enhancing SEO by avoiding incorrect language tags.

Implementing Language Support Per Page

Each tool's landing page checks for language support within its JSON file. This determines the hreflang tags and ensures content renders in the specified language, resorting to English if the chosen language is unavailable.

<script setup lang="ts">
import { filterHreflangLinks } from '~/utils/hreflang'
// Checks and setups omitted for brevity
</script>

Ensuring Robust Fallbacks

Vue components can break if a locale key is absent. Implementing a safe accessor function prevents crashes by providing fallback content, typically in English, ensuring a seamless user experience.

Streamlined Language Addition

Adding a new language becomes a straightforward process of updating JSON files rather than altering code. This method allows BulkPicTools to efficiently manage multilingual support across its 38 landing pages.