Skip to main content

Blog Tag Management Guide

Overview​

This document explains how blog tags are managed consistently across all 8 supported locales (en, zh, ja, ko, es, de, pt, ru) in the BlockEden.xyz CMS.

Problem Statement​

Previously, blog tags were defined inline in each post's front matter without centralized management. This led to:

  1. Cross-locale tag pollution: Chinese tags appearing on Spanish site (/es/blog/tags/法定货币/) causing 404 errors
  2. Inconsistent capitalization: blockchain vs Blockchain, sui vs Sui
  3. Translation issues: Tags being translated inconsistently or not at all
  4. No single source of truth: Hard to maintain consistency across 370+ unique tags

Solution: Centralized Tags.yml System​

We now use Docusaurus's built-in tags.yml feature to manage tags centrally:

blog/tags.yml                                          # English (canonical)
i18n/zh/docusaurus-plugin-content-blog/tags.yml      # Simplified Chinese
i18n/ja/docusaurus-plugin-content-blog/tags.yml      # Japanese
i18n/ko/docusaurus-plugin-content-blog/tags.yml      # Korean
i18n/es/docusaurus-plugin-content-blog/tags.yml      # Spanish
i18n/de/docusaurus-plugin-content-blog/tags.yml      # German
i18n/pt/docusaurus-plugin-content-blog/tags.yml      # Portuguese
i18n/ru/docusaurus-plugin-content-blog/tags.yml      # Russian

Tag Categories​

Tags are categorized into groups with different translation rules:

1. Blockchain Networks (Never Translate)​

Keep in English across all locales:

  • Ethereum, Sui, Aptos, Bitcoin, Solana, Cardano, Polygon

Example:

# blog/tags.yml
Ethereum:
  label: 'Ethereum'
  permalink: '/ethereum'
  description: 'Articles about Ethereum blockchain'

# i18n/zh/docusaurus-plugin-content-blog/tags.yml
Ethereum:
  label: 'Ethereum'  # Keep in English
  permalink: '/ethereum'
  description: '关于以太坊区块链、智能合约和生态系统的文章'  # Translate description

2. Technical Protocols (Never Translate)​

Keep in English:

  • Web3, DeFi, NFT, API, DAO, Layer 2, zkp

3. Crypto/Finance Terms (Never Translate)​

Keep in English:

  • crypto, stablecoins, tokenization, staking, MEV

4. General Business Terms (Always Translate)​

Translate to target language:

  • product → 产品 (zh), producto (es), 製品 (ja)
  • company → 公司 (zh), empresa (es), 会社 (ja)
  • partnership → 合作伙伴关系 (zh), asociación (es)

5. Industry Terms (Translate)​

Translate to target language:

  • blockchain → 区块链 (zh), Blockchain (es), ブロックチェーン (ja)
  • fintech → 金融科技 (zh), fintech (es), フィンテック (ja)
  • security → 安全 (zh), Seguridad (es), セキュリティ (ja)

File Structure​

English Tags (blog/tags.yml)​

# Blockchain Networks (keep in English)
Ethereum:
  label: 'Ethereum'
  permalink: '/ethereum'
  description: 'Articles about Ethereum blockchain'

# Business Terms (translate)
product:
  label: 'Product'
  permalink: '/product'
  description: 'Product updates and announcements'

Localized Tags (i18n/{locale}/docusaurus-plugin-content-blog/tags.yml)​

# Spanish (i18n/es/docusaurus-plugin-content-blog/tags.yml)
Ethereum:
  label: 'Ethereum'  # Keep in English
  permalink: '/ethereum'
  description: 'Artículos sobre blockchain de Ethereum'

product:
  label: 'Producto'  # Translated
  permalink: '/product'
  description: 'Actualizaciones y anuncios de productos'

How It Works​

1. Blog Plugin Configuration​

In docusaurus.config.ts:

blog: {
  // ... other config
  tags: "tags.yml",
  onInlineTags: "warn", // Warn about tags not in tags.yml
},

2. Using Tags in Blog Posts​

In blog post front matter, reference tags by their key from tags.yml:

---
title: "My Blog Post"
tags: [Ethereum, product, blockchain]  # Use keys from tags.yml
---

3. Automatic Tag Mapping​

The translation script (scripts/i18n.js) automatically:

  1. Extracts tags from English blog post
  2. Translates the post content
  3. Maps tags to locale-specific versions using tags.yml
  4. Updates the translated post with correct tags

Scripts​

1. Fix Existing Blog Tags​

Fix tags in already-translated blog posts:

# Dry run (check what would be fixed)
node scripts/fix-blog-tags.js --dry-run

# Fix all locales
node scripts/fix-blog-tags.js

# Fix specific locale(s)
node scripts/fix-blog-tags.js es
node scripts/fix-blog-tags.js zh ja ko

Output:

╔═════════════════════════════════════════════════════════╗
║        Blog Tags Fix Script - BlockEden.xyz CMS        ║
╚═════════════════════════════════════════════════════════╝

Mode: WRITE (changes will be saved)
Locales: es

============================================================
Fixing locale: ES
============================================================
  ✏️  2025-09-27-wall-street-macro-shift.md:
    Current: [cambio macroeconómico, 法定货币, criptomonedas]
    Updated: [cambio macroeconómico, moneda fiduciaria, criptomonedas]
  ✓ 2025-02-21-cardano-research.md: Tags already correct

Results for es:
  Checked: 246 files
  Fixed: 1 files

============================================================
OVERALL SUMMARY
============================================================
Total locales processed: 1
Total files fixed: 1

✅ All done! Blog tags have been fixed.

2. Translate New Blog Posts​

When you run the translation script, it will automatically map tags:

yarn i18n

The script will:

  1. Translate blog post content
  2. Extract English tags
  3. Map to locale-specific tags
  4. Save with correct tags

Adding New Tags​

Step 1: Add to English tags.yml​

Edit blog/tags.yml:

# New blockchain network
Base:
  label: 'Base'
  permalink: '/base'
  description: 'Articles about Base Layer 2 network'

# New business term
ecosystem:
  label: 'Ecosystem'
  permalink: '/ecosystem'
  description: 'Blockchain ecosystem news and updates'

Step 2: Add to All Locale Files​

Add the same tag key to each locale's tags.yml:

Chinese (i18n/zh/docusaurus-plugin-content-blog/tags.yml):

Base:
  label: 'Base'  # Keep blockchain names in English
  permalink: '/base'
  description: '关于 Base Layer 2 网络的文章'

ecosystem:
  label: '生态系统'  # Translate business terms
  permalink: '/ecosystem'
  description: '区块链生态系统新闻和更新'

Spanish (i18n/es/docusaurus-plugin-content-blog/tags.yml):

Base:
  label: 'Base'
  permalink: '/base'
  description: 'Artículos sobre la red Base Layer 2'

ecosystem:
  label: 'Ecosistema'
  permalink: '/ecosystem'
  description: 'Noticias y actualizaciones del ecosistema blockchain'

Repeat for all other locales (ja, ko, de, pt, ru).

Step 3: Use in Blog Posts​

Now you can use the new tags:

---
title: "Building on Base"
tags: [Base, ecosystem, DeFi]
---

Tag Naming Guidelines​

1. Use Consistent Case​

  • Blockchain names: Proper case (Ethereum, Sui, not ethereum, sui)
  • Acronyms: All caps (API, NFT, DAO)
  • Technical terms: As commonly written (DeFi, Web3, not defi, web3)
  • General terms: Lowercase (product, company, not Product, Company)

2. Use Descriptive Keys​

Use slug-friendly keys that are easy to reference:

✅ Good:

smart-contracts:
  label: 'Smart Contracts'

institutional-investment:
  label: 'Institutional Investment'

❌ Avoid:

sc:  # Too cryptic
  label: 'Smart Contracts'

"Smart Contracts":  # Spaces in key
  label: 'Smart Contracts'

3. Avoid Duplicates​

Check for existing similar tags before adding new ones:

❌ Avoid:

blockchain:
  label: 'Blockchain'

blockchain-tech:
  label: 'Blockchain Technology'

blockchain-innovation:
  label: 'Blockchain Innovation'

✅ Better:

blockchain:
  label: 'Blockchain'
  description: 'General blockchain technology and innovation'

Validation​

Check for Invalid Tags​

The blog plugin will warn about inline tags not in tags.yml:

yarn build

Output:

[WARNING] Inline tag "NewTag" not found in tags.yml
  in blog/2025-12-01-new-post.md

Switch to Strict Mode​

Once all tags are migrated, change to strict mode in docusaurus.config.ts:

blog: {
  tags: "tags.yml",
  onInlineTags: "throw", // Fail build if tags not in tags.yml
},

Troubleshooting​

Q: I see Chinese tags on the Spanish site​

A: Run the fix script:

node scripts/fix-blog-tags.js es

Q: New blog posts have untranslated tags​

A: Make sure the tag exists in blog/tags.yml and all locale files. Then re-run translation:

yarn i18n

Q: Build fails with "Tag not found" error​

A: Add the missing tag to blog/tags.yml and all locale tags.yml files, or remove it from the blog post.

Q: How do I find all uses of a specific tag?​

A: Search blog posts:

grep -r "tags:.*YourTag" blog/
grep -r "tags:.*YourTag" i18n/*/docusaurus-plugin-content-blog/

Best Practices​

  1. Always add new tags to tags.yml first before using them in blog posts
  2. Keep blockchain names and technical terms in English across all locales
  3. Translate business/general terms to provide localized user experience
  4. Run the fix script after bulk changes to ensure consistency
  5. Use meaningful, descriptive tag labels that users will understand
  6. Group related content using consistent tags for better discoverability
  7. Review tag usage regularly to consolidate duplicates

Migration Checklist​

  • Create blog/tags.yml with canonical English tags
  • Create locale-specific tags.yml files (zh, ja, ko, es, de, pt, ru)
  • Configure blog plugin to use tags.yml
  • Update translation script to map tags automatically
  • Create fix-blog-tags.js script to fix existing posts
  • Run fix script for all locales
  • Test build locally
  • Verify tag pages work correctly for each locale
  • Monitor Google Search Console for 404 errors
  • Switch onInlineTags to 'throw' after validation

Resources​

Share on Twitter