بنية المشروع

فهم دليل .lingo/ ومحتوياته.

نظرة عامة على الدليل

عند تشغيل المترجم لأول مرة، يقوم بإنشاء دليل .lingo/ في جذر مشروعك:

your-project/
├── .lingo/
│   ├── metadata.json
│   ├── locale-resolver.server.ts (optional)
│   └── locale-resolver.client.ts (optional)
├── src/
├── package.json
└── ...

metadata.json

الملف الأساسي الذي يحتوي على جميع بيانات الترجمة.

البنية

{
  "version": "1",
  "sourceLocale": "en",
  "targetLocales": ["es", "de", "fr"],
  "translations": {
    "abc123def456": {
      "source": "Welcome to our app",
      "context": {
        "file": "app/page.tsx",
        "line": 12,
        "component": "HomePage"
      },
      "locales": {
        "es": "Bienvenido a nuestra aplicación",
        "de": "Willkommen in unserer App",
        "fr": "Bienvenue dans notre application"
      },
      "metadata": {
        "createdAt": "2024-01-15T10:30:00Z",
        "updatedAt": "2024-01-15T10:30:00Z"
      }
    }
  }
}

الحقول الرئيسية

الإصدار: إصدار تنسيق البيانات الوصفية. الحالي: "1"

اللغات المصدر/الهدف: اللغات المكونة لديك

الترجمات: تعيين قائم على التجزئة لجميع النصوص القابلة للترجمة:

• التجزئة (abc123def456): معرّف ثابت بناءً على النص المصدر + السياق
• source: النص الإنجليزي الأصلي
• context: مكان ظهور هذا النص (الملف، السطر، المكون)
• locales: الترجمات لكل لغة مستهدفة
• metadata: وقت إنشاء/تحديث الترجمة

توليد التجزئة

التجزئات حتمية:

• بناءً على النص المصدر + سياق المكون
• نفس النص في مواقع مختلفة = تجزئات مختلفة
• يتيح ترجمات واعية بالسياق

مثال:

// app/home/page.tsx
<button>Submit</button> // Hash: abc123

// app/checkout/page.tsx
<button>Submit</button> // Hash: def456 (different context)

محللات اللغة المخصصة

ملفات اختيارية لتخصيص اكتشاف اللغة والاستمرارية.

locale-resolver.server.ts

اكتشاف اللغة من جانب الخادم (Next.js فقط):

// .lingo/locale-resolver.server.ts
export async function getServerLocale(): Promise<string> {
  // Your custom logic
  return "en";
}

locale-resolver.client.ts

اكتشاف اللغة والاستمرارية من جانب العميل:

// .lingo/locale-resolver.client.ts
export function getClientLocale(): string {
  // Detect locale
  return "en";
}

export function persistLocale(locale: string): void {
  // Save locale preference
}

إذا لم تكن هذه الملفات موجودة، يستخدم المترجم السلوك الافتراضي المعتمد على ملفات تعريف الارتباط.

راجع محللات اللغة المحلية المخصصة للحصول على التفاصيل.

التحكم في الإصدار

هل يجب عليك إرسال .lingo/؟

نعم. يجب أن يكون دليل .lingo/ تحت التحكم في الإصدار:

إرسال:

• metadata.json — يحتوي على جميع الترجمات
• محللات اللغة المحلية المخصصة (إذا تم إنشاؤها)

عدم الإرسال:

• لا شيء — يجب إرسال جميع الملفات في .lingo/

لماذا إرسال الترجمات؟

1. التحكم في الإصدار — تتبع تغييرات الترجمة جنبًا إلى جنب مع الكود
2. التعاون الجماعي — مشاركة الترجمات عبر الفريق
3. CI/CD — تستخدم إصدارات الإنتاج الترجمات المرسلة
4. سجل المراجعة — معرفة متى تغيرت الترجمات ولماذا

تكامل Git

أضف .lingo/ إلى مستودعك:

git add .lingo/
git commit -m "chore: update translations"
git push

يقوم المترجم تلقائيًا بتحديث .lingo/metadata.json عندما:

• تتم إضافة نص جديد قابل للترجمة
• يتم تعديل النص الموجود
• يتم إنشاء الترجمات

قم بإرسال هذه التحديثات بانتظام.

حجم الملف

ينمو metadata.json مع تطبيقك:

• تطبيق صغير (50 سلسلة نصية): ~10 كيلوبايت
• تطبيق متوسط (500 سلسلة نصية): ~100 كيلوبايت
• تطبيق كبير (5000 سلسلة نصية): ~1 ميجابايت

هذا أمر طبيعي ومقبول للتحكم في الإصدار.

التنظيف

إزالة الترجمات غير المستخدمة

بمرور الوقت، قد تتراكم لديك ترجمات غير مستخدمة (من المكونات المحذوفة).

التنظيف اليدوي:

1. ابحث عن التجزئة في قاعدة الكود الخاصة بك
2. إذا لم يتم العثور عليها، احذفها من metadata.json

التنظيف التلقائي (قريبًا):

npx @lingo.dev/compiler clean

سيؤدي هذا إلى إزالة الترجمات غير المستخدمة تلقائيًا.

إعادة تعيين الترجمات

لإعادة إنشاء جميع الترجمات من الصفر:

# Backup current translations
cp .lingo/metadata.json .lingo/metadata.backup.json

# Delete metadata
rm .lingo/metadata.json

# Regenerate
npm run dev # or npm run build

الترحيل

من المترجم القديم

استخدم المترجم القديم بنية ملفات مختلفة:

القديم:

lingo/
├── dictionary.js
├── meta.json
└── [locale]/
    └── *.json

الجديد:

.lingo/
└── metadata.json

الترحيل غير آلي. راجع دليل الترحيل للحصول على التفاصيل.

فحص الترجمات

العرض في المحرر

افتح .lingo/metadata.json في محررك:

{
  "translations": {
    "abc123": {
      "source": "Welcome",
      "locales": {
        "es": "Bienvenido"
      }
    }
  }
}

البحث عن ترجمة

ابحث عن الترجمة بواسطة النص المصدر:

grep -r "Welcome" .lingo/metadata.json

البحث بواسطة الهاش

grep -r "abc123" .lingo/metadata.json

طباعة منسقة

cat .lingo/metadata.json | jq '.'

الأسئلة الشائعة

هل يمكنني تعديل metadata.json يدويًا؟ نعم، لكن غير مستحسن. استخدم data-lingo-override بدلاً من ذلك—فهو أكثر أمانًا ومتحكم في الإصدار في الكود المصدري.

ماذا لو حذفت metadata.json؟ يقوم المترجم بإعادة إنشائه في البناء التالي. سيتم إنشاء جميع الترجمات من جديد (يكلف أرصدة API).

هل يمكنني نقل .lingo/ إلى دليل مختلف؟ نعم. قم بالتكوين عبر خيار lingoDir:

{
  lingoDir: "translations"
}

هل يحتوي metadata.json على بيانات حساسة؟ لا. يحتوي فقط على النص المصدر والترجمات—لا توجد مفاتيح API أو أسرار.

هل يمكنني دمج metadata.json من فروع متعددة؟ نعم. يتعامل Git مع عمليات الدمج تلقائيًا. التعارضات نادرة (الهاشات فريدة).

ماذا لو أضاف فرعان نفس الترجمة؟ يدمجها Git تلقائيًا. إذا اختلفت الهاشات (سياق مختلف)، يتم الاحتفاظ بكليهما.

الخطوات التالية

• محللات اللغة المخصصة — تخصيص الاستمرارية
• أدوات التطوير — العمل مع المترجم الزائف
• أوضاع البناء — فهم سلوك التخزين المؤقت