مرجع الإعدادات
مرجع كامل لجميع خيارات إعدادات @lingo.dev/compiler.
الخيارات الأساسية
| الخيار | النوع | الافتراضي | الوصف |
|---|---|---|---|
sourceRoot | string | "src" | الدليل الجذر الذي يحتوي على الكود المصدري للترجمة |
lingoDir | string | ".lingo" | دليل البيانات الوصفية للترجمة والذاكرة المؤقتة |
sourceLocale | string | (مطلوب) | رمز اللغة المصدر (مثل "en"، "en-US") |
targetLocales | string[] | (مطلوب) | مصفوفة رموز اللغات المستهدفة للترجمة إليها |
useDirective | boolean | false | ما إذا كان يتطلب توجيه 'use i18n' للاشتراك في الترجمة |
models | string | object | "lingo.dev" | إعدادات موفر الترجمة (راجع موفرو الترجمة) |
prompt | string | undefined | قالب مخصص لمطالبة الترجمة |
buildMode | "translate" | "cache-only" | "translate" | وضع البناء (راجع أوضاع البناء) |
مثال
{
sourceRoot: "./app",
lingoDir: ".lingo",
sourceLocale: "en",
targetLocales: ["es", "de", "fr", "ja"],
useDirective: false,
models: "lingo.dev",
buildMode: "translate",
}
خيارات التطوير
قم بتكوين السلوك الخاص بالتطوير عبر كائن dev:
| الخيار | النوع | الافتراضي | الوصف |
|---|---|---|---|
dev.usePseudotranslator | boolean | false | استخدام ترجمات وهمية بدلاً من الذكاء الاصطناعي الحقيقي (موصى به للتطوير) |
dev.translationServerStartPort | number | 60000 | منفذ البداية لخادم الترجمة (يبحث تلقائياً 60000-60099) |
dev.translationServerUrl | string | undefined | عنوان URL مخصص لخادم الترجمة (استخدام متقدم) |
مثال
{
dev: {
usePseudotranslator: true, // Fast fake translations
translationServerStartPort: 60000, // Default port range
}
}
لماذا المترجم الزائف؟ إنه فوري (بدون استدعاءات API)، ويعرض بالضبط ما يتم ترجمته، ويختبر واجهة المستخدم الخاصة بك بأطوال نصية متفاوتة—كل ذلك بدون تكاليف API.
استمرارية اللغة
قم بتكوين كيفية الاحتفاظ بتغييرات اللغة:
| الخيار | النوع | الافتراضي | الوصف |
|---|---|---|---|
localePersistence.type | "cookie" | "cookie" | حاليًا يتم دعم الاستمرارية المستندة إلى ملفات تعريف الارتباط فقط |
localePersistence.config.name | string | "locale" | اسم ملف تعريف الارتباط |
localePersistence.config.maxAge | number | 31536000 | الحد الأقصى لعمر ملف تعريف الارتباط بالثواني (الافتراضي: سنة واحدة) |
مثال
{
localePersistence: {
type: "cookie",
config: {
name: "user-locale",
maxAge: 31536000, // 1 year
},
},
}
استمرارية مخصصة؟ قم بتنفيذ محللات اللغة المخصصة لاستخدام localStorage أو معاملات URL أو استمرارية قاعدة البيانات.
صيغ الجمع
قم بتكوين الكشف التلقائي عن صيغ الجمع:
| الخيار | النوع | الافتراضي | الوصف |
|---|---|---|---|
pluralization.enabled | boolean | true | تمكين الكشف التلقائي عن تنسيق ICU MessageFormat |
pluralization.model | string | "groq:llama-3.1-8b-instant" | نموذج LLM المستخدم للكشف عن صيغ الجمع |
مثال
{
pluralization: {
enabled: true,
model: "groq:llama-3.1-8b-instant", // Fast model for plural detection
},
}
كيف يعمل: يكتشف المترجم صيغ الجمع في النص الخاص بك (مثل "لديك 5 عناصر") ويحولها إلى تنسيق ICU MessageFormat ({count, plural, one {1 item} other {# items}}).
تعطيل للأداء: إذا كنت لا تستخدم صيغ الجمع، قم بتعطيل هذا لتخطي استدعاءات LLM لصيغ الجمع.
موفرو الترجمة
يقوم خيار models بتكوين موفر (موفري) LLM المستخدم للترجمات.
التكوين البسيط
استخدم موفرًا واحدًا لجميع الترجمات:
{
models: "lingo.dev" // Recommended: Lingo.dev Engine
}
الإعدادات المتقدمة
استخدم تعيين أزواج اللغات للتحكم الدقيق:
{
models: {
"en:es": "groq:llama-3.3-70b-versatile", // English to Spanish
"en:de": "google:gemini-2.0-flash", // English to German
"*:fr": "openai:gpt-4o", // Any locale to French
"*:*": "anthropic:claude-3-5-sonnet", // Fallback for all others
}
}
الأنماط:
"source:target": زوج لغة محدد (مثل"en:es")"*:target": أي مصدر إلى هدف محدد (مثل"*:de")"source:*": مصدر محدد إلى أي هدف (مثل"en:*")"*:*": احتياطي لجميع الأزواج
راجع موفرو الترجمة لبناء جملة الموفر وإعداد مفتاح API.
مطالبات الترجمة المخصصة
خصص مطالبة الترجمة باستخدام العناصر النائبة:
{
prompt: `Translate from {SOURCE_LOCALE} to {TARGET_LOCALE}.
Use a formal tone and preserve all technical terms.
Do not translate brand names or product names.`
}
العناصر النائبة المتاحة:
{SOURCE_LOCALE}: رمز اللغة المصدر (مثل"en"){TARGET_LOCALE}: رمز اللغة الهدف (مثل"es")
يضيف المترجم سياقاً حول النص الذي يتم ترجمته (موقع المكون، العناصر المحيطة) إلى مطالبتك المخصصة.
تجاوز متغير البيئة
تجاوز الإعدادات عبر متغيرات البيئة:
# Override build mode
LINGO_BUILD_MODE=cache-only npm run build
# Set API key
LINGODOTDEV_API_KEY=your_key_here
GROQ_API_KEY=gsk_...
GOOGLE_API_KEY=...
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
MISTRAL_API_KEY=...
OPENROUTER_API_KEY=...
مثال كامل
// next.config.ts
import type { NextConfig } from "next";
import { withLingo } from "@lingo.dev/compiler/next";
const nextConfig: NextConfig = {};
export default async function (): Promise<NextConfig> {
return await withLingo(nextConfig, {
// Core
sourceRoot: "./app",
lingoDir: ".lingo",
sourceLocale: "en",
targetLocales: ["es", "de", "fr", "ja"],
useDirective: false,
// Build mode
buildMode: process.env.NODE_ENV === "production" ? "cache-only" : "translate",
// Models
models: {
"en:es": "groq:llama-3.3-70b-versatile",
"*:*": "lingo.dev",
},
// Custom prompt
prompt: "Translate from {SOURCE_LOCALE} to {TARGET_LOCALE}. Use a professional tone.",
// Development
dev: {
usePseudotranslator: true,
translationServerStartPort: 60000,
},
// Locale persistence
localePersistence: {
type: "cookie",
config: {
name: "locale",
maxAge: 31536000,
},
},
// Pluralization
pluralization: {
enabled: true,
model: "groq:llama-3.1-8b-instant",
},
});
}
أنواع TypeScript
استورد أنواع الإعدادات لضمان أمان الأنواع:
import type { LingoConfig } from "@lingo.dev/compiler";
const config: LingoConfig = {
// ...config
};
الأسئلة الشائعة
هل أحتاج إلى تكوين جميع الخيارات؟
لا. فقط sourceLocale وtargetLocales مطلوبان. جميع الخيارات الأخرى لها قيم افتراضية معقولة.
ما الفرق بين sourceRoot و lingoDir؟
sourceRoot هو المكان الذي يوجد فيه الكود المصدري الخاص بك (مثل ./app، src). lingoDir هو المكان الذي يتم فيه تخزين البيانات الوصفية للترجمة (افتراضي: .lingo).
هل يمكنني استخدام نماذج مختلفة لكل لغة؟
نعم. استخدم تعيين أزواج اللغات في خيار models. راجع موفرو الترجمة.
هل يجب أن أرسل .lingo/ إلى git؟
نعم. يحتوي دليل .lingo/ على البيانات الوصفية للترجمة والذاكرة المؤقتة. يجب التحكم في إصداره جنباً إلى جنب مع الكود الخاص بك.
كيف يمكنني تعطيل الجمع؟
قم بتعيين pluralization.enabled: false. يؤدي هذا إلى تخطي اكتشاف صيغ الجمع وتقليل استدعاءات LLM.
الخطوات التالية
- موفرو الترجمة — تكوين موفري LLM
- أوضاع البناء — فهم الترجمة مقابل التخزين المؤقت فقط
- محللات اللغة المخصصة — تنفيذ اكتشاف اللغة المخصص
- أفضل الممارسات — التكوينات الموصى بها