Arabic Localization

Arabic Localization Standards

This skill defines the standardized approach to Arabic internationalization (i18n) for SaaS applications, covering file structure, naming conventions, and tone variations.

File Structure

Directory Organization

locales/
├── en/
│   ├── common.json
│   ├── auth.json
│   ├── dashboard.json
│   └── errors.json
└── ar/
    ├── common.json
    ├── auth.json
    ├── dashboard.json
    └── errors.json

Namespace Strategy

Core Namespaces (Always Required):

• common.json - Shared UI elements, navigation, actions
• auth.json - Authentication, registration, password flows
• errors.json - Error messages, validation feedback
• dashboard.json - Main application interface

Feature-Specific Namespaces:

• onboarding.json - User onboarding flows
• settings.json - User preferences and configuration
• billing.json - Payments and subscriptions
• notifications.json - Alerts and notification messages
• help.json - Help center and documentation

Translation Key Naming Conventions

Hierarchical Structure

{
  "namespace": {
    "section": {
      "component": {
        "element": "Translation"
      }
    }
  }
}

Practical Examples

// common.json
{
  "nav": {
    "home": "الرئيسية",
    "dashboard": "لوحة التحكم",
    "settings": "الإعدادات"
  },
  "actions": {
    "save": "حفظ",
    "cancel": "إلغاء",
    "delete": "حذف",
    "confirm": "تأكيد",
    "edit": "تعديل",
    "create": "إنشاء"
  },
  "status": {
    "loading": "جاري التحميل...",
    "success": "تم بنجاح",
    "error": "حدث خطأ",
    "empty": "لا توجد بيانات"
  }
}

// auth.json
{
  "login": {
    "title": "تسجيل الدخول",
    "email": "البريد الإلكتروني",
    "password": "كلمة المرور",
    "submit": "تسجيل الدخول",
    "forgotPassword": "نسيت كلمة المرور؟",
    "noAccount": "ليس لديك حساب؟"
  },
  "register": {
    "title": "إنشاء حساب جديد",
    "fullName": "الاسم الكامل",
    "confirmPassword": "تأكيد كلمة المرور",
    "terms": "أوافق على الشروط والأحكام",
    "submit": "إنشاء حساب"
  },
  "validation": {
    "emailRequired": "البريد الإلكتروني مطلوب",
    "emailInvalid": "صيغة البريد الإلكتروني غير صحيحة",
    "passwordTooShort": "كلمة المرور قصيرة جداً",
    "passwordMismatch": "كلمات المرور غير متطابقة"
  }
}

// errors.json
{
  "network": {
    "offline": "لا يوجد اتصال بالإنترنت",
    "timeout": "انتهت مهلة الطلب",
    "serverError": "خطأ في الخادم، يرجى المحاولة لاحقاً"
  },
  "auth": {
    "invalidCredentials": "بيانات الدخول غير صحيحة",
    "sessionExpired": "انتهت صلاحية الجلسة",
    "unauthorized": "غير مصرح لك بالوصول"
  },
  "validation": {
    "required": "هذا الحقل مطلوب",
    "invalidFormat": "الصيغة غير صحيحة",
    "tooLong": "القيمة طويلة جداً",
    "tooShort": "القيمة قصيرة جداً"
  }
}

Key Naming Rules

1. Use camelCase for keys: forgotPassword, emailAddress
2. Be descriptive but concise: loginSubmit not btn1
3. Group related translations: auth.login.*, auth.register.*
4. Consistent patterns: All buttons end with action: save, cancel, submit
5. Avoid redundancy: login.title not login.loginTitle

Tone Variation Guidelines

Arabic has distinct tone variations based on context and audience. This section defines three standard tones: Najdi, Professional, and Modern Standard Arabic (MSA).

Tone Selection Matrix

Tone-Specific File Structure (Advanced)

For applications requiring multiple tones:

locales/
└── ar/
    ├── common.json          # Default (MSA)
    ├── common-najdi.json    # Najdi variant
    ├── common-pro.json      # Professional variant
    └── auth.json            # Shared across tones

Implementation:

// Load tone-specific translations
const locale = 'ar';
const tone = user.preferences.tone || 'msa'; // 'najdi', 'professional', 'msa'

const translations = {
  ...require(`./locales/${locale}/common.json`),
  ...(tone !== 'msa' ? require(`./locales/${locale}/common-${tone}.json`) : {})
};

Najdi Dialect Characteristics

When to Use:

• Consumer-facing apps targeting Gulf region (Saudi Arabia, Kuwait, UAE, Qatar)
• Casual, friendly interactions
• Marketing and engagement content
• Social features and community interactions

Linguistic Features:

• Informal pronouns: "إنت" (you - masculine), "إنتي" (you - feminine)
• Shortened words: "شلون" instead of "كيف حالك"
• Regional expressions: "زين" (good), "يلا" (let's go)
• Casual tone with emotional warmth

Examples:

{
  "greeting": "هلا وغلا! 👋",
  "welcome": "أهلاً فيك",
  "howAreYou": "شلونك؟",
  "good": "زين",
  "thanks": "يعطيك العافية",
  "bye": "يلا باي",
  "wait": "شوي شوي",
  "done": "تمام",
  "error": "في مشكلة",
  "help": "تبي مساعدة؟"
}

Complete Example (Najdi):

// common-najdi.json
{
  "dashboard": {
    "welcome": "هلا {name}، شلونك اليوم؟",
    "empty": "ما فيه شي هنا",
    "tryAgain": "جرب مرة ثانية"
  },
  "notifications": {
    "newMessage": "عندك رسالة جديدة",
    "reminder": "لا تنسى!",
    "success": "تمام! اشتغل زين"
  }
}

Professional Modern Tone

When to Use:

• B2B applications
• Corporate environments
• Professional services platforms
• Enterprise SaaS
• Financial applications

Linguistic Features:

• Formal but not archaic
• Clear, concise language
• Modern terminology for tech concepts
• Professional distance while remaining accessible
• Avoids overly formal classical structures

Examples:

{
  "greeting": "مرحباً",
  "welcome": "أهلاً بك",
  "howAreYou": "كيف حالك؟",
  "good": "جيد",
  "thanks": "شكراً",
  "bye": "إلى اللقاء",
  "wait": "يرجى الانتظار",
  "done": "تم بنجاح",
  "error": "حدث خطأ",
  "help": "هل تحتاج مساعدة؟"
}

Complete Example (Professional):

// common-pro.json
{
  "dashboard": {
    "welcome": "مرحباً {name}، نتمنى لك يوماً مثمراً",
    "empty": "لا توجد بيانات متاحة",
    "tryAgain": "حاول مرة أخرى"
  },
  "notifications": {
    "newMessage": "لديك رسالة جديدة",
    "reminder": "تذكير هام",
    "success": "تمت العملية بنجاح"
  },
  "actions": {
    "save": "حفظ التغييرات",
    "cancel": "إلغاء العملية",
    "delete": "حذف نهائي",
    "confirm": "تأكيد الإجراء"
  }
}

Modern Standard Arabic (MSA)

When to Use:

• Government applications
• Educational platforms
• Pan-Arab audience (multi-country)
• Formal documentation
• Legal and compliance content
• Default fallback for unknown audiences

Linguistic Features:

• Classical grammar structures
• Formal vocabulary
• Universal comprehension across Arab world
• Minimal regional dialect influences
• Appropriate for serious/official contexts

Examples:

{
  "greeting": "السلام عليكم",
  "welcome": "أهلاً وسهلاً بكم",
  "howAreYou": "كيف حالكم؟",
  "good": "حسناً",
  "thanks": "شكراً جزيلاً",
  "bye": "مع السلامة",
  "wait": "يُرجى الانتظار",
  "done": "اكتملت العملية",
  "error": "حدث خطأ ما",
  "help": "هل تحتاجون إلى المساعدة؟"
}

Complete Example (MSA):

// common.json (default MSA)
{
  "dashboard": {
    "welcome": "مرحباً بكم {name}، نأمل أن تكونوا بخير",
    "empty": "لا توجد بيانات لعرضها",
    "tryAgain": "يُرجى المحاولة مرة أخرى"
  },
  "notifications": {
    "newMessage": "لديكم رسالة جديدة",
    "reminder": "تذكير",
    "success": "نجحت العملية"
  },
  "terms": {
    "agreement": "اتفاقية الاستخدام",
    "privacy": "سياسة الخصوصية",
    "accept": "أوافق على الشروط والأحكام"
  }
}

Comparative Examples

Same Content, Three Tones

Scenario: Welcome Message

// Najdi
"welcome": "هلا فيك! شلونك اليوم؟ إن شاء الله بخير 🌟"

// Professional
"welcome": "مرحباً بك! نتمنى لك تجربة ممتعة ومثمرة."

// MSA
"welcome": "أهلاً وسهلاً بكم. نأمل أن تحظوا بتجربة مُرضية."

Scenario: Error Message

// Najdi
"error": "في مشكلة! جرب مرة ثانية يا ريت"

// Professional
"error": "حدث خطأ. يرجى المحاولة مرة أخرى"

// MSA
"error": "حدث خطأ ما. يُرجى المحاولة مرة أخرى"

Scenario: Call to Action

// Najdi
"cta": "يلا! سجّل الحين واستمتع 🚀"

// Professional
"cta": "سجّل الآن واستفد من جميع المزايا"

// MSA
"cta": "سجّلوا الآن للاستفادة من كافة الخدمات"

Pluralization Rules

Arabic has complex pluralization (singular, dual, plural, many). Use i18n libraries that support ICU message format:

{
  "items": {
    "zero": "لا توجد عناصر",
    "one": "عنصر واحد",
    "two": "عنصران",
    "few": "{{count}} عناصر",
    "many": "{{count}} عنصراً",
    "other": "{{count}} عنصر"
  }
}

React i18next Example:

import { useTranslation } from 'react-i18next';

const { t } = useTranslation();

// Automatically handles pluralization
<span>{t('items', { count: itemCount })}</span>

Gender-Aware Translations

Arabic adjectives and verbs change based on gender. Handle with context:

{
  "welcome": {
    "male": "مرحباً بك",
    "female": "مرحباً بكِ"
  },
  "ready": {
    "male": "أنت جاهز",
    "female": "أنتِ جاهزة"
  }
}

Implementation:

const gender = user.gender || 'neutral';
t(`welcome.${gender}`, { fallback: t('welcome.male') });

Date and Time Formatting

{
  "date": {
    "format": "DD/MM/YYYY",
    "months": [
      "يناير", "فبراير", "مارس", "إبريل", "مايو", "يونيو",
      "يوليو", "أغسطس", "سبتمبر", "أكتوبر", "نوفمبر", "ديسمبر"
    ],
    "days": [
      "الأحد", "الاثنين", "الثلاثاء", "الأربعاء", 
      "الخميس", "الجمعة", "السبت"
    ]
  },
  "time": {
    "am": "ص",
    "pm": "م",
    "format": "hh:mm A"
  }
}

Use Hijri Calendar for Gulf Region (Optional):

{
  "calendar": {
    "type": "hijri", // or "gregorian"
    "locale": "ar-SA"
  }
}

Number Formatting

Arabic uses Eastern Arabic numerals (٠١٢٣٤٥٦٧٨٩) or Western (0123456789):

{
  "numbers": {
    "useEasternNumerals": true, // ١٢٣ vs 123
    "decimalSeparator": "٫",
    "thousandsSeparator": "٬"
  }
}

Implementation:

const formatNumber = (num: number, locale: string) => {
  return new Intl.NumberFormat(locale === 'ar' ? 'ar-SA' : 'en-US').format(num);
};

formatNumber(1234567.89, 'ar'); // ١٬٢٣٤٬٥٦٧٫٨٩ or 1,234,567.89

Implementation Checklist

• Namespace structure created (common, auth, errors, etc.)
• Translation keys follow camelCase convention
• Hierarchical key organization implemented
• Tone variation selected (Najdi / Professional / MSA)
• Pluralization rules configured for Arabic
• Gender-aware translations where applicable
• Date/time formatting configured
• Number formatting decided (Eastern vs Western numerals)
• RTL text direction coordinated (see rtl-ui skill)
• Fallback language (English) available
• i18n library configured (react-i18next, next-i18next, etc.)
• Translation validation in place (no missing keys)
• Context provided for ambiguous translations

Common Mistakes to Avoid

1. Using Google Translate directly - Results in unnatural phrasing
2. Mixing tones inconsistently - Choose one tone and stick to it
3. Ignoring pluralization rules - Arabic has 6 plural forms
4. Direct word-for-word translation - Arabic requires restructuring
5. Forgetting gender context - Affects verbs and adjectives
6. Using wrong numerals - Eastern vs Western varies by region
7. Hardcoding dates in UI - Use locale-aware formatting
8. Over-formal tone for consumer apps - Najdi is more engaging
9. Too casual for B2B - Professional or MSA is appropriate
10. Not testing with native speakers - Always validate with target audience

Extended Resources

Additional Documentation

This skill includes supplementary documentation for detailed examples:

tone-examples.md - Comprehensive tone comparison examples:

• Side-by-side comparisons across all three tones
• E-commerce flow examples
• Email templates in all tones
• Dashboard content examples
• Marketing copy variations
• Real-world scenario comparisons

To access detailed examples, agents should read tone-examples.md located in this skill directory.

Resources

For detailed tone examples and additional context, see tone-examples.md in this skill directory.

Tone Selection Quick Guide:

• Gulf Region Consumer App? → Use Najdi
• B2B / Corporate Platform? → Use Professional
• Multi-Country / Formal? → Use MSA
• Unsure? → Start with MSA, can always localize later