metaplex-foundation_developer-hub/SEO_IMPLEMENTATION.md

SEO Implementation for Multilingual Documentation

Date: 2025-10-12 Status: ✅ Complete

Overview

This document outlines the SEO implementation for the Metaplex Developer Hub's multilingual documentation, following international best practices for language-specific content.

Changes Made

1. Language Code Standardization

Updated from custom codes to ISO 639-1 standard:

Old Code	New Code	Language	Reason
/jp/	/ja/	Japanese	ISO 639-1 standard for Japanese
/kr/	/ko/	Korean	ISO 639-1 standard for Korean

Why This Matters:

• hreflang tags require ISO 639-1 language codes
• Improves international SEO
• Aligns with web standards
• Prevents confusion with search engines

2. New SEO Components

Language Configuration (src/config/languages.js)

Central configuration for all language settings:

• ISO 639-1 language codes
• URL path mappings
• Native language names
• Helper functions for path generation

SEOHead Component (src/components/SEOHead.jsx)

Comprehensive SEO meta tags including:

• Title and Description: Translated for each language
• Canonical URLs: Self-referential (each language version points to itself)
• hreflang Tags: Proper alternate language links
• Open Graph: Language-aware OG tags with locale alternates
• Twitter Card: Complete social media meta tags

3. File Migrations

Directories Renamed

• /src/pages/jp/ → /src/pages/ja/ (437 files)
• /src/pages/kr/ → /src/pages/ko/ (437 files)

Locale Files Renamed

• /src/locales/jp.json → /src/locales/ja.json
• /src/locales/kr.json → /src/locales/ko.json

4. Configuration Updates

Updated Files

1. src/contexts/LocaleContext.js

   • Changed locale detection from jp/kr to ja/ko
   • Updated import paths for locale JSON files

2. src/components/LanguageSwitcher.jsx

   • Updated language codes to ja and ko
   • Updated path detection logic

3. src/shared/localizedSections.js

   • Changed translation keys from jp/kr to ja/ko

4. src/shared/productTranslations.js

   • Added Korean (ko) translations
   • Changed Japanese key from jp to ja

5. src/i18n.js

   • Updated locale array: ['en', 'ja', 'ko']

6. src/pages/_app.jsx

   • Replaced custom Head implementation with new SEOHead component
   • Now automatically generates all SEO tags

SEO Features Implemented

✅ Canonical URLs

Each language version has a self-referential canonical URL:

• English: https://developers.metaplex.com/page
• Japanese: https://developers.metaplex.com/ja/page
• Korean: https://developers.metaplex.com/ko/page

✅ hreflang Tags

Every page includes alternate language links:

<link rel="alternate" hreflang="en" href="https://developers.metaplex.com/page" />
<link rel="alternate" hreflang="ja" href="https://developers.metaplex.com/ja/page" />
<link rel="alternate" hreflang="ko" href="https://developers.metaplex.com/ko/page" />
<link rel="alternate" hreflang="x-default" href="https://developers.metaplex.com/page" />

✅ Open Graph Localization

• og:locale set to proper format (e.g., ja_JP, ko_KR)
• og:locale:alternate tags for other languages
• Prevents duplicate content issues

✅ Translated Meta Tags

• Page titles translated in frontmatter
• Meta descriptions translated
• All social media cards properly localized

URL Structure

Final URL Pattern

• English (default): developers.metaplex.com/[page]
• Japanese: developers.metaplex.com/ja/[page]
• Korean: developers.metaplex.com/ko/[page]

Example Pages

English	Japanese	Korean
/core	/ja/core	/ko/core
/candy-machine	/ja/candy-machine	/ko/candy-machine
/umi	/ja/umi	/ko/umi

Adding New Languages

To add a new language in the future:

1. Update Language Config (src/config/languages.js):

   es: {
    code: 'es',           // ISO 639-1 code
    urlPath: '/es',       // URL prefix
    name: 'Spanish',
    nativeName: 'Español',
    isDefault: false,
   }
   

2. Create Locale File: /src/locales/es.json

3. Update i18n Config (src/i18n.js):

   const locales = ['en', 'ja', 'ko', 'es'];
   

4. Add Translations to:

   • src/shared/localizedSections.js
   • src/shared/productTranslations.js

5. Create Pages Directory: /src/pages/es/

The SEO system will automatically:

• Generate hreflang tags
• Create canonical URLs
• Add Open Graph locale tags
• Handle language switching

Testing SEO

Verify Implementation

1. Check hreflang tags: View page source and look for <link rel="alternate" hreflang="..."
2. Test canonical URLs: Ensure each language version has correct self-referential canonical
3. Validate Open Graph: Use Facebook Sharing Debugger
4. Check Twitter Cards: Use Twitter Card Validator

Google Search Console

After deployment:

1. Submit all language versions to Search Console
2. Monitor for any hreflang errors
3. Verify language targeting is working correctly

Benefits

✅ No Duplicate Content Penalties: Each language version properly identified ✅ Improved International SEO: Search engines serve correct language to users ✅ Better User Experience: Users see content in their preferred language ✅ Future-Proof: Easy to add more languages ✅ Standards Compliant: Follows W3C and Google best practices

References

• Google Search Central - Localized Versions
• ISO 639-1 Language Codes
• hreflang Best Practices
• Open Graph Protocol