الحفاظ على المفاتيح

Lingo.dev CLI يتيح لك الحفاظ على مفاتيح ترجمة محددة بحيث يتم تهيئتها مرة واحدة ولا يتم استبدالها أبدًا بواسطة عمليات CLI اللاحقة. يتم نسخ المفاتيح المحفوظة من المصدر كعناصر نائبة، ثم حمايتها من تحديثات الترجمة التلقائية.

عند الحفاظ على المفاتيح، يقوم CLI بتهيئتها بقيم المصدر ثم يتخطاها أثناء عمليات الترجمة المستقبلية.

إعداد الحفاظ على المفاتيح

أضف preservedKeys إلى تكوين الحاوية الخاصة بك في i18n.json:

{
  "locale": {
    "source": "en",
    "targets": ["es", "fr", "de"]
  },
  "buckets": {
    "json": {
      "include": ["locales/[locale].json"],
      "preservedKeys": ["legal/privacy", "legal/terms", "marketing/tagline"]
    }
  }
}

يستخدم مصفوفة preservedKeys تدوين الشرطة المائلة (/) لتحديد المفاتيح المتداخلة والنجمة (*) لمطابقة مفاتيح متعددة.

كيفية عمل الحفاظ على المفاتيح

أثناء معالجة الترجمة، يقوم Lingo.dev CLI بـ:

1. تحديد المفاتيح المحفوظة من التكوين الخاص بك
2. استبعادها من الترجمة — لا يتم إرسال المفاتيح المحفوظة أبدًا إلى محرك الترجمة
3. تهيئة المفاتيح المفقودة — نسخ قيم المصدر كعناصر نائبة للملفات المستهدفة الجديدة
4. حماية القيم الموجودة — الحفاظ على المحتوى المترجم يدويًا دون تغيير

مثال على سير العمل:

// locales/en.json (source)
{
  "welcome": "Welcome to our platform",
  "legal": {
    "privacy": "We respect your privacy and protect your data.",
    "terms": "By using this service, you agree to our terms."
  }
}

مع تكوين المفاتيح المحفوظة:

{
  "preservedKeys": ["legal/privacy", "legal/terms"]
}

الترجمة الإسبانية المُنشأة (التشغيل الأول):

// locales/es.json (generated)
{
  "welcome": "Bienvenido a nuestra plataforma",
  "legal": {
    "privacy": "We respect your privacy and protect your data.",
    "terms": "By using this service, you agree to our terms."
  }
}

يتم ترجمة مفتاح welcome. يتم نسخ قسم legal كما هو للترجمة اليدوية لاحقًا.

مسارات المفاتيح المتداخلة

استخدم تدوين الشرطة المائلة (/) للحفاظ على المفاتيح في أي عمق:

{
  "preservedKeys": [
    "legal/privacy/full",
    "legal/terms/conditions",
    "marketing/campaigns/holiday"
  ]
}

يعمل هذا التدوين مع الهياكل المتداخلة المعقدة:

// Source structure
{
  "legal": {
    "privacy": {
      "full": "Full privacy policy text..."
    }
  }
}

يحافظ المسار legal/privacy/full على هذا المفتاح المتداخل المحدد.

المفاتيح التي تحتوي على نقاط

يتعامل تدوين الشرطة المائلة مع المفاتيح التي تحتوي على نقاط في أسمائها:

// Source with dotted key names
{
  "legal": {
    "privacy.policy": "Privacy policy content",
    "terms.of.service": "Terms of service content"
  }
}

احفظ هذه المفاتيح باستخدام:

{
  "preservedKeys": ["legal/privacy.policy", "legal/terms.of.service"]
}

أنواع الحاويات المتعددة

يمكن أن تحتوي تنسيقات الملفات المختلفة على مفاتيح محفوظة مختلفة:

{
  "buckets": {
    "json": {
      "include": ["locales/[locale].json"],
      "preservedKeys": ["legal/privacy", "legal/terms"]
    },
    "yaml": {
      "include": ["translations/[locale].yml"],
      "preservedKeys": ["compliance/gdpr", "compliance/ccpa"]
    }
  }
}

يحتفظ كل نوع من أنواع الحاويات بقائمة المفاتيح المحفوظة الخاصة به بناءً على بنية المحتوى.

الحفاظ على المفاتيح مقابل قفل المفاتيح

الحفاظ على المفاتيح وقفل المفاتيح يخدمان أغراضًا مختلفة:

الحفاظ على المفاتيح (preservedKeys):

• يتم تهيئة المفاتيح مرة واحدة بقيم المصدر كعناصر نائبة
• لا يتم الكتابة فوق قيم الهدف الموجودة بواسطة واجهة سطر الأوامر مطلقًا
• تُستخدم للمحتوى الذي يتطلب ترجمة يدوية أو مراجعة قانونية

قفل المفاتيح (lockedKeys):

• يتم تضمين المفاتيح في معالجة الترجمة ولكن القيم تظل دون تغيير
• تطابق المفاتيح المقفلة دائمًا قيم المصدر تمامًا
• تُستخدم للمعرفات التقنية أو أسماء المكونات أو القيم التي يجب أن تظل متسقة

مثال للمقارنة:

// Source file
{
  "welcome": "Welcome",
  "system": {
    "component": "Lingo.dev Engine"
  },
  "legal": {
    "privacy": "Privacy policy text"
  }
}

// Configuration
{
  "lockedKeys": ["system/component"],
  "preservedKeys": ["legal/privacy"]
}

// Generated target file
{
  "welcome": "Bienvenido",
  "system": {
    "component": "Lingo.dev Engine"
  },
  "legal": {
    "privacy": "Privacy policy text"
  }
}

بعد ترجمة legal/privacy يدويًا إلى الإسبانية، تحتفظ العمليات اللاحقة بالترجمة اليدوية. يظل مفتاح system/component دائمًا باللغة الإنجليزية بغض النظر عن محتوى الملف الهدف.