استكشاف الأخطاء وإصلاحها

المشكلات الشائعة والحلول عند استخدام @lingo.dev/compiler.

مشكلات التثبيت

"Cannot find module '@lingo.dev/compiler'"

السبب: الحزمة غير مثبتة أو مثبتة بشكل غير صحيح.

الحل:

npm install @lingo.dev/compiler
# or
pnpm install @lingo.dev/compiler

التحقق من التثبيت:

ls node_modules/@lingo.dev/compiler

"Module not found: Can't resolve '@lingo.dev/compiler/react'"

السبب: الاستيراد من مسار خاطئ أو حزمة قديمة.

الحل:

التحقق من عبارة الاستيراد:

import { LingoProvider } from "@lingo.dev/compiler/react"; // Correct

إعادة تثبيت الحزمة:
```
rm -rf node_modules
npm install
```

مشكلات التكوين

"Config must be async function" (Next.js)

السبب: تكوين Next.js غير مغلف في دالة async.

الحل:

// Wrong
export default withLingo(nextConfig, {...});

// Correct
export default async function (): Promise<NextConfig> {
  return await withLingo(nextConfig, {...});
}

"sourceLocale is required"

السبب: sourceLocale مفقود في التكوين.

الحل:

{
  sourceLocale: "en", // Required
  targetLocales: ["es", "de"],
}

"targetLocales must be an array"

السبب: targetLocales ليس مصفوفة أو فارغ.

الحل:

{
  targetLocales: ["es", "de"], // Must be array with at least one locale
}

مشاكل الترجمة

الترجمات لا تظهر

الأعراض: يظهر النص باللغة المصدر فقط.

الأسباب والحلول:

1. لم تتم إضافة LingoProvider أو في موقع خاطئ

// Wrong - too low in tree
export default function Page() {
  return (
    <LingoProvider>
      <Content />
    </LingoProvider>
  );
}

// Correct - in root layout
export default function RootLayout({ children }) {
  return (
    <LingoProvider>
      <html>
        <body>{children}</body>
      </html>
    </LingoProvider>
  );
}

2. ترجمات مفقودة في البيانات الوصفية تحقق من .lingo/metadata.json:

{
  "translations": {
    "abc123": {
      "locales": {
        "es": "..." // Should have translation
      }
    }
  }
}

إذا كان فارغاً أو مفقوداً، قم بالتشغيل مع buildMode: "translate":

npm run dev # or build

3. وضع البناء هو cache-only بدون ترجمات مخزنة مؤقتاً

# Generate translations first
LINGO_BUILD_MODE=translate npm run build

# Then use cache-only
LINGO_BUILD_MODE=cache-only npm run build

جميع الترجمات "[!!! ...]"

السبب: المترجم الزائف مفعّل.

الحل:

{
  dev: {
    usePseudotranslator: false, // Disable for real translations
  }
}

أعد تشغيل خادم التطوير.

بعض النصوص لا تتم ترجمتها

الأسباب:

1. محتوى ديناميكي أو خصائص

// Not translated (yet) - string in variable
const title = "Welcome";
<h1>{title}</h1>

// Translated - string in JSX
<h1>Welcome</h1>

الحل: يتم تحسين المترجم لدعم السلاسل النصية الحرفية. في الوقت الحالي، ضع النص مباشرة في JSX.

2. النص في السمات يتطلب معالجة خاصة

// Translated automatically
<img alt="Logo" />
<button aria-label="Close" />

// May need explicit handling
<div custom-attr="Some text" /> // Not translated unless configured

3. useDirective مفعّل إذا كان useDirective: true، فإن الملفات التي لا تحتوي على 'use i18n' لن تُترجم.

الحل: أضف التوجيه:

'use i18n';

export function Component() { ... }

مشاكل البناء

"ترجمات مفقودة للغة X"

السبب: buildMode: "cache-only" لكن الترجمات مفقودة.

الحل:

قم بإنشاء الترجمات:

npm run dev # or
LINGO_BUILD_MODE=translate npm run build

قم بحفظ .lingo/metadata.json
أعد المحاولة باستخدام cache-only

"فشل إنشاء الترجمة"

الأسباب:

1. مفتاح API غير صالح

# Check .env file
cat .env | grep API_KEY

تأكد من صحة مفتاح API الخاص بمزود الخدمة.

2. مشاكل في الشبكة اختبر اتصال API:

curl https://api.openai.com/v1/models \
  -H "Authorization: Bearer $OPENAI_API_KEY"

3. تحديد المعدل قلل سرعة إنشاء الترجمات أو قم بترقية مستوى API.

4. تكوين نموذج غير صالح

// Wrong
{
  models: {
    "*:*": "invalid-provider:model",
  }
}

// Correct
{
  models: {
    "*:*": "groq:llama-3.3-70b-versatile",
  }
}

البناء بطيء

الأسباب:

1. إنشاء العديد من الترجمات أول عملية بناء مع نص جديد تكون بطيئة. عمليات البناء اللاحقة تكون سريعة (محفوظة مؤقتاً).

2. المترجم الزائف معطّل في بيئة التطوير

{
  dev: {
    usePseudotranslator: true, // Enable for fast development
  }
}

3. تفعيل صيغ الجمع بشكل غير ضروري

{
  pluralization: {
    enabled: false, // Disable if not using plural forms
  }
}

مشاكل HMR

HMR لا يعمل

السبب: موضع LingoProvider أو إعدادات إطار العمل.

الحلول:

Next.js: تأكد من وضع LingoProvider في التخطيط الجذري، وليس في التخطيطات المتداخلة.

Vite: تأكد من وضع lingoCompilerPlugin قبل إضافة react():

plugins: [
  lingoCompilerPlugin({...}), // Before react plugin
  react(),
]

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

السبب: إعادة تحميل الصفحة بسبب تغيير اللغة.

السلوك المتوقع: setLocale() يعيد تحميل الصفحة افتراضياً لتطبيق اللغة الجديدة.

لتجنب إعادة التحميل: قم بتنفيذ persistLocale مخصص بدون إعادة تحميل:

// .lingo/locale-resolver.client.ts
export function persistLocale(locale: string): void {
  localStorage.setItem("locale", locale);
  // Don't call window.location.reload()
}

ملاحظة: يتطلب هذا تحميل الترجمات مسبقاً لجميع اللغات.

مشاكل API/المصادقة

"مفتاح API غير صالح"

الحلول:

1. تحقق من اسم متغير البيئة

# Lingo.dev Engine
LINGODOTDEV_API_KEY=...

# OpenAI
OPENAI_API_KEY=sk-...

# Anthropic
ANTHROPIC_API_KEY=sk-ant-...

2. تحقق من أن مفتاح API نشط قم بتسجيل الدخول إلى لوحة تحكم المزود وتحقق من حالة المفتاح.

3. أعد تشغيل خادم التطوير بعد إضافة المفتاح

npm run dev

يتم تحميل متغيرات البيئة عند بدء التشغيل.

"فشلت المصادقة" (Lingo.dev)

الحلول:

1. إعادة المصادقة

npx lingo.dev@latest login

2. مفتاح API يدوي

# Add to .env
LINGODOTDEV_API_KEY=your_key_here

احصل على المفتاح من إعدادات المشروع في lingo.dev.

المتصفح يحظر تدفق المصادقة

السبب: متصفح Brave أو الإضافات تحظر المصادقة.

الحل: أضف مفتاح API يدويًا إلى .env:

LINGODOTDEV_API_KEY=...

مشاكل الخادم

"فشل بدء خادم الترجمة"

السبب: جميع المنافذ من 60000 إلى 60099 قيد الاستخدام.

الحلول:

1. تكوين نطاق منافذ مختلف

{
  dev: {
    translationServerStartPort: 61000,
  }
}

2. إنهاء العمليات الموجودة

# Find processes using ports
lsof -i :60000-60099

# Kill process
kill -9 <PID>

"المنفذ 60000 قيد الاستخدام بالفعل"

السبب: عملية أخرى تستخدم هذا المنفذ.

الحل: يعثر الخادم تلقائيًا على المنفذ المتاح التالي. تحقق من وحدة التحكم لمعرفة المنفذ الفعلي:

[lingo] Translation server started on port 60001

إذا كانت جميع المنافذ مشغولة، راجع "فشل بدء خادم الترجمة" أعلاه.

أخطاء الأنواع

"الخاصية 'data-lingo-override' غير موجودة"

السبب: TypeScript لا يتعرف على السمة.

الحل: أضف تصريح النوع:

// global.d.ts
declare namespace React {
  interface HTMLAttributes<T> {
    "data-lingo-override"?: Record<string, string>;
  }
}

أو استخدم علامات الاقتباس:

<div {"data-lingo-override"}={{ es: "..." }}>
  Text
</div>

"خطأ في النوع: يجب أن يُرجع Config قيمة Promise"

السبب: إعدادات Next.js غير مكتوبة بشكل صحيح.

الحل:

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, {...});
}

مشاكل الإنتاج

الترجمات مفقودة في الإنتاج

الأسباب:

1. المجلد .lingo/ غير مُرسل

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

2. وضع بناء الإنتاج خاطئ

// Should be cache-only in production
{
  buildMode: "cache-only",
}

3. CI لم يُنشئ الترجمات تحقق من سجلات CI — تأكد من أن الترجمات تم إنشاؤها وإرسالها.

ترجمات مختلفة في التطوير مقابل الإنتاج

السبب: المترجم الزائف مُفعّل في الإنتاج.

الحل:

{
  dev: {
    usePseudotranslator: process.env.NODE_ENV === "development", // Only in dev
  }
}

الحصول على المساعدة

إذا كنت لا تزال عالقاً:

تحقق من السجلات — ابحث عن رسائل الخطأ في وحدة التحكم
تحقق من .lingo/metadata.json — تحقق من البنية والمحتويات
اختبر باستخدام المترجم الزائف — عزل مشاكل API
تحقق من مشاكل GitHub — github.com/lingodotdev/lingo.dev/issues
اسأل على Discord — discord.gg/lingo

عند طلب المساعدة، قم بتضمين:

رسالة الخطأ (تتبع المكدس الكامل)
الإعدادات (next.config.ts أو vite.config.ts)
إصدارات الحزم (npm list @lingo.dev/compiler)
خطوات إعادة الإنتاج

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

س: هل أحتاج إلى مفاتيح API في الإنتاج؟ ج: لا، مع buildMode: "cache-only". يتم إنشاء الترجمات مسبقاً في CI.

س: لماذا يفشل البناء الخاص بي؟ ج: تحقق من رسالة الخطأ. الأسباب الشائعة: ترجمات مفقودة، مفتاح API غير صالح، مشاكل في الشبكة.

س: هل يمكنني استخدام موفري LLM متعددين؟ ج: نعم، مع تعيين أزواج اللغات في إعدادات models.

س: كيف يمكنني الاختبار دون تكاليف API؟ ج: قم بتفعيل usePseudotranslator: true في التطوير.

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

مرجع الإعدادات — راجع جميع الخيارات
أفضل الممارسات — تجنب المشاكل الشائعة
كيف يعمل — افهم النظام