CSV لكل لغة - Lingo.dev CLI

ما هو CSV لكل لغة؟

CSV لكل لغة هو نهج ترجمة حيث يكون لكل لغة ملف CSV منفصل خاص بها، بدلاً من تخزين جميع اللغات في ملف CSV واحد بأعمدة متعددة. هذا التنسيق مفيد عندما يكون لديك بيانات منظمة بأعمدة متعددة (مثل كتالوجات المنتجات أو بيانات المستخدمين أو أنظمة إدارة المحتوى) حيث يمثل كل صف سجلاً وتمثل الأعمدة حقولاً مختلفة.

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

id,name,description,created,enabled,sort
1,Welcome,Welcome to our application,2024-01-01,true,1
2,Save,Save your changes,2024-01-01,true,2
3,Error,An error occurred,2024-01-01,true,3

على عكس حاوية CSV القياسية التي تخزن جميع اللغات في ملف واحد بأعمدة مثل KEY,en,es، تحافظ حاوية csv-per-locale على ملفات منفصلة لكل لغة، مع الحفاظ على بنية CSV الأصلية بجميع الأعمدة.

ما هو Lingo.dev CLI؟

Lingo.dev CLI هو واجهة سطر أوامر مجانية ومفتوحة المصدر لترجمة التطبيقات والمحتوى بالذكاء الاصطناعي. تم تصميمه ليحل محل برامج إدارة الترجمة التقليدية مع التكامل مع خطوط الأنابيب الحالية.

لمعرفة المزيد، راجع نظرة عامة.

حول هذا الدليل

يشرح هذا الدليل كيفية ترجمة ملفات CSV باستخدام حاوية csv-per-locale مع Lingo.dev CLI.

ستتعلم كيفية:

إنشاء مشروع من الصفر
تكوين خط أنابيب ترجمة مع ملفات CSV منفصلة لكل لغة
إنشاء ترجمات بالذكاء الاصطناعي
استخدام المفاتيح المقفلة والمتجاهلة

المتطلبات الأساسية

لاستخدام Lingo.dev CLI، تأكد من تثبيت Node.js الإصدار 18 أو أحدث:

❯ node -v
v22.17.0

الخطوة 1. إعداد المشروع

في دليل مشروعك، أنشئ ملف i18n.json:

{
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.10",
  "locale": {
    "source": "en",
    "targets": ["es"]
  },
  "buckets": {}
}

يحدد هذا الملف سلوك خط أنابيب الترجمة، بما في ذلك اللغات المراد الترجمة بينها ومكان وجود المحتوى القابل للترجمة على نظام الملفات.

لمعرفة المزيد عن الخصائص المتاحة، راجع i18n.json.

الخطوة 2. تكوين اللغة المصدر

اللغة المصدر هي اللغة والمنطقة الأصلية التي كُتب بها المحتوى الخاص بك. لتكوين اللغة المصدر، قم بتعيين خاصية locale.source في ملف i18n.json:

{
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.10",
  "locale": {
    "source": "en",
    "targets": ["es"]
  },
  "buckets": {}
}

يجب توفير اللغة المصدر كـ علامة لغة BCP 47.

للحصول على القائمة الكاملة لرموز اللغات التي يدعمها Lingo.dev CLI، راجع رموز اللغات المدعومة.

الخطوة 3. تكوين اللغات المستهدفة

اللغات المستهدفة هي اللغات والمناطق التي تريد ترجمة المحتوى الخاص بك إليها. لتكوين اللغات المستهدفة، قم بتعيين خاصية locale.targets في ملف i18n.json:

{
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.10",
  "locale": {
    "source": "en",
    "targets": ["es"]
  },
  "buckets": {}
}

الخطوة 4. إنشاء المحتوى المصدر

إذا لم تكن قد قمت بذلك بالفعل، قم بإنشاء ملف CSV للغة المصدر الخاصة بك. يجب أن يحتوي الملف على:

صف رأس يحتوي على أسماء الأعمدة
صف بيانات واحد أو أكثر
أي أعمدة تحتاجها (غير محدودة بأسماء أعمدة معينة)

يجب أن يكون ملف CSV موجوداً في مسار يتضمن اللغة المصدر في مكان ما من المسار (على سبيل المثال، كاسم دليل مثل en/ أو كجزء من اسم الملف مثل data.en.csv).

ملاحظة: على عكس حاوية CSV القياسية، لا تحتاج إلى عمود "KEY" أو عمود يطابق اللغة المصدر. تتعامل حاوية csv-per-locale مع كل صف كسجل وستترجم جميع محتويات النص في ملف CSV مع الحفاظ على البنية.

الخطوة 5. إنشاء حاوية

في ملف i18n.json، أضف كائن "csv-per-locale" إلى كائن buckets:

{
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.10",
  "locale": {
    "source": "en",
    "targets": ["es"]
  },
  "buckets": {
    "csv-per-locale": {}
  }
}

في كائن "csv-per-locale"، حدد مصفوفة من نمط include واحد أو أكثر:

{
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.10",
  "locale": {
    "source": "en",
    "targets": ["es"]
  },
  "buckets": {
    "csv-per-locale": {
      "include": ["./[locale]/example.csv"]
    }
  }
}

تحدد هذه الأنماط الملفات التي سيتم ترجمتها.

الأنماط نفسها:

يجب أن تحتوي على [locale] كعنصر نائب للغة المحلية المكونة
يمكن أن تشير إلى مسارات الملفات (مثل "[locale]/data.csv")
يمكن استخدام العلامات النجمية كعناصر نائبة بديلة (مثل "[locale]/*.csv")

أنماط glob العودية (مثل **/*.csv) غير مدعومة.

اختيارياً، يمكنك تكوين lockedKeys و ignoredKeys:

{
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.10",
  "locale": {
    "source": "en",
    "targets": ["es"]
  },
  "buckets": {
    "csv-per-locale": {
      "include": ["./[locale]/example.csv"],
      "lockedKeys": ["locked_key_1"],
      "ignoredKeys": ["ignored_key_1"]
    }
  }
}

lockedKeys: المفاتيح (قيم الأعمدة في العمود الأول، عادةً معرّف) التي لا ينبغي ترجمتها
ignoredKeys: المفاتيح التي لا ينبغي أن تظهر في ملفات اللغة المحلية المستهدفة

الخطوة 6. تكوين نموذج لغوي كبير

يستخدم Lingo.dev CLI نماذج لغوية كبيرة (LLMs) لترجمة المحتوى باستخدام الذكاء الاصطناعي. لاستخدام أحد هذه النماذج، تحتاج إلى مفتاح API من مزود مدعوم.

للبدء بأسرع وقت ممكن، نوصي باستخدام Lingo.dev Engine — منصتنا المستضافة الخاصة التي توفر 10,000 رمز مميز من الاستخدام المجاني الشهري:

سجل للحصول على حساب Lingo.dev.
قم بتشغيل الأمر التالي:
```
npx lingo.dev@latest login
```

سيؤدي هذا إلى فتح متصفحك الافتراضي ويطلب منك المصادقة.

اتبع التعليمات.

الخطوة 7. إنشاء الترجمات

في الدليل الذي يحتوي على ملف i18n.json، قم بتشغيل الأمر التالي:

npx lingo.dev@latest run

هذا الأمر:

يقرأ ملف i18n.json.
يجد الملفات التي تحتاج إلى ترجمة.
يستخرج المحتوى القابل للترجمة من ملفات CSV.
يستخدم نموذج اللغة الكبير المُكوَّن لترجمة المحتوى المستخرج.
يكتب المحتوى المترجم مرة أخرى إلى ملفات CSV منفصلة لكل لغة مستهدفة.

في المرة الأولى التي يتم فيها إنشاء الترجمات، يتم إنشاء ملف i18n.lock. يتتبع هذا الملف المحتوى الذي تمت ترجمته، مما يمنع إعادة الترجمة غير الضرورية في عمليات التشغيل اللاحقة.

مثال

en/example.csv (قبل الترجمة)

id,name,description,created,enabled,sort
1,Welcome,Welcome to our application,2024-01-01,true,1
2,Save,Save your changes,2024-01-01,true,2
3,Error,An error occurred,2024-01-01,true,3
4,Success,Operation completed successfully,2024-01-01,true,4
5,Loading,Please wait while we load your data,2024-01-01,true,5

es/example.csv (بعد الترجمة)

id,name,description,created,enabled,sort
1,Bienvenida,Bienvenido a nuestra aplicación,2024-01-01,true,1
2,Guardar,Guarda tus cambios,2024-01-01,true,2
3,Error,Ha ocurrido un error,2024-01-01,true,3
4,Éxito,Operación completada con éxito,2024-01-01,true,4
5,Cargando,Por favor espera mientras cargamos tus datos,2024-01-01,true,5

i18n.json

{
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.10",
  "locale": {
    "source": "en",
    "targets": ["es"]
  },
  "buckets": {
    "csv-per-locale": {
      "include": ["./[locale]/example.csv"],
      "lockedKeys": ["locked_key_1"],
      "ignoredKeys": ["ignored_key_1"]
    }
  }
}

i18n.lock

version: 1
checksums:
  e8b273672f895de0944f0a2317670d7c:
    0/name: 1308168cca4fa5d8d7a0cf24e55e93fc
    0/description: 8de4bc8832b11b380bc4cbcedc16e48b
    1/name: f7a2929f33bc420195e59ac5a8bcd454
    1/description: 8de4bc8832b11b380bc4cbcedc16e48b
    2/name: d3d99b147cc363dc6db8a48e8a13d4c1
    2/description: 7cd986af1fe5e89abe7ecffba5413110

الفروقات عن حاوية CSV

تختلف حاوية csv-per-locale عن حاوية csv القياسية في عدة جوانب:

بنية الملف: تستخدم csv-per-locale ملفات منفصلة لكل لغة (مثل en/example.csv، es/example.csv)، بينما تستخدم csv ملفاً واحداً بأعمدة متعددة (مثل KEY,en,es).
متطلبات الأعمدة: لا تتطلب csv-per-locale عمود "KEY" أو أعمدة مسماة باللغات. يمكنك استخدام أي بنية أعمدة تناسب بياناتك.
حالات الاستخدام: تعتبر csv-per-locale مثالية للبيانات المنظمة مثل كتالوجات المنتجات أو أنظمة إدارة المحتوى أو قواعد البيانات حيث يمثل كل صف سجلاً بحقول متعددة. حاوية csv القياسية أكثر ملاءمة لجداول الترجمة البسيطة من نوع مفتاح-قيمة.
تعديلات الملفات: تقوم كلتا الحاويتين بتعديل الملفات مباشرة، لكن csv-per-locale تنشئ ملفات منفصلة لكل لغة، بينما تضيف csv أعمدة جديدة إلى الملف الموجود.