الانتقال إلى المحتوى الرئيسي

دليل عملي: موقع Hugo متعدد اللغات

قم بإعداد نظام تعدد اللغات في Hugo بحيث يتولى champollion ترجمة كل من ملفات النصوص بصيغة JSON ومحتوى Markdown. يغطي هذا الدليل سير العمل الكامل من إعداد المشروع إلى النشر في بيئة الإنتاج.

ما الذي ستبنيه: موقع Hugo بالإنجليزية والفرنسية واليابانية — ترجمة النصوص عبر ملفات اللغات، وترجمة المحتوى عبر معالجة ملفات Markdown.

هيكل المشروع​

يستخدم Champollion وضع الترجمة القائم على أسماء الملفات في Hugo. تُوضع الملفات المترجمة في نفس مجلد الملف المصدر، مع إضافة لاحقة اللغة إلى اسم الملف (مثل about.fr.md):

my-hugo-site/
├── content/
│   └── en/
│       ├── _index.md
│       ├── _index.fr.md           ← champollion generates
│       ├── _index.ja.md           ← champollion generates
│       ├── about.md
│       ├── about.fr.md            ← champollion generates
│       ├── about.ja.md            ← champollion generates
│       └── blog/
│           ├── first-post.md
│           ├── first-post.fr.md   ← champollion generates
│           └── first-post.ja.md   ← champollion generates
├── i18n/
│   ├── en.json
│   ├── fr.json                    ← champollion generates
│   └── ja.json                    ← champollion generates
└── hugo.toml

:::note أوضاع i18n في Hugo يدعم Hugo استراتيجيتين للترجمة: القائمة على أسماء الملفات (about.fr.md بجوار about.md) والقائمة على المجلدات (أشجار content/fr/about.md منفصلة). يستخدم Champollion الترجمة القائمة على أسماء الملفات لأن الدالة getTargetContentPath() الخاصة به تولّد المسارات الهدف بإضافة لاحقة اللغة إلى اسم الملف المصدر. تأكد من أن hugo.toml لديك مُهيّأ للترجمة القائمة على أسماء الملفات عند استخدام champollion. :::

الخطوة 1: تهيئة Hugo​

hugo.toml
defaultContentLanguage = 'en'

[languages]
  [languages.en]
    languageName = 'English'
    weight = 1
  [languages.fr]
    languageName = 'Français'
    weight = 2
  [languages.ja]
    languageName = '日本語'
    weight = 3

الخطوة 2: تهيئة Champollion​

يحتاج Champollion إلى تهيئة أمرين: مسار ملف اللغة (لنصوص JSON) ومجلد المحتوى (لملفات Markdown).

champollion.config.json
{
  "version": 3,
  "inputLocale": "en",
  "localesDir": "./i18n",
  "contentDir": "./content",
  "model": "google/gemini-3.5-flash",
  "pairs": {
    "en:fr": { "method": "llm" },
    "en:ja": { "method": "llm", "model": "openai/gpt-4o" }
  },
  "languages": {
    "fr": { "name": "French", "register": "Formal (vous-form)" },
    "ja": { "name": "Japanese", "register": "Polite/formal" }
  }
}

الخطوة 3: إنشاء المحتوى المصدر​

ترجمات النصوص (i18n/)​

i18n/en.json
{
  "nav": {
    "home": "Home",
    "about": "About",
    "blog": "Blog",
    "contact": "Contact"
  },
  "footer": {
    "copyright": "© 2026 My Company. All rights reserved.",
    "privacy": "Privacy Policy"
  }
}

محتوى Markdown ‏(content/en/)​

content/en/about.md
---
title: "About Us"
description: "Learn more about our team and mission"
date: 2026-01-15
---

We build software that helps businesses communicate across languages.

Our platform supports **real-time translation** for over 30 languages,
with specialized support for low-resource languages.

## Our Mission

Language should never be a barrier to understanding.

## The Team

{{< team-grid >}}

الخطوة 4: تشغيل المزامنة​

npx champollion sync

يعالج Champollion كلا النوعين:

  1. ملفات النصوص (i18n/en.json ← i18n/fr.json، i18n/ja.json)
  2. ملفات المحتوى (content/en/about.md ← content/en/about.fr.md، content/en/about.ja.md)

تفاصيل ترجمة المحتوى​

عند ترجمة ملفات Markdown، يقوم champollion تلقائيًا بما يلي:

  • حماية كتل التعليمات البرمجية، والرموز المختصرة ({{< ... >}})، والتعليمات البرمجية المضمّنة، وعناصر HTML
  • ترجمة حقول الواجهة الأمامية للملف (title، description، summary)
  • الحفاظ على جميع حقول الواجهة الأمامية الأخرى (date، draft، weight، tags)
  • استعادة الكتل المحمية بعد الترجمة

يمر الرمز المختصر الخاص بـ Hugo {{< team-grid >}} دون ترجمة.

الخطوة 5: التحقق​

# Preview the site
hugo server

# Check translation status
npx champollion status

انتقل إلى localhost:1313/fr/ و localhost:1313/ja/ لمراجعة المحتوى المترجم.

الخطوة 6: مبدّل اللغة في Hugo​

أضف مبدّل لغة إلى تخطيط Hugo الخاص بك:

layouts/partials/language-switcher.html
<nav class="language-switcher">
  {{ range $.Site.Home.AllTranslations }}
    <a href="{{ .Permalink }}"
       {{ if eq .Lang $.Site.Language.Lang }}class="active"{{ end }}>
      {{ .Language.LanguageName }}
    </a>
  {{ end }}
</nav>

إبقاء المحتوى متزامنًا​

عند تحديث المحتوى الإنجليزي، شغّل المزامنة مرة أخرى. يعيد Champollion ترجمة الملفات التي تغيّرت فقط:

# Edit content/en/about.md, then:
npx champollion sync

يتتبع ملف القفل تجزئات المحتوى لكل ملف، لذا لا تُعاد ترجمة الصفحات التي لم تتغير.

انظر أيضًا​