איך לתרגם אפליקציית Next.js עם PolyLingo בפחות מ-30 דקות

בסוף המדריך הזה יהיה לך פרויקט Next.js App Router רב-לשוני עובד: מחרוזות מופרדות לקובץ messages/en.json, קבצי locale מתורגמים לכל שפה שתצטרך, next-intl שמשרת את הקובץ הנכון לכל נתיב, וסקריפט Node יחיד שתוכל להריץ מחדש בכל פעם שהתוכן שלך משתנה.

אין צורך להירשם לפלטפורמת תרגום. אין תשלום קבוע לכל שפה. קריאת API אחת מטפלת בכל שפות היעד שלך בבת אחת.

מה תצטרך:

פרויקט Next.js שמשתמש ב-App Router (Next.js 14 או 15)
Node.js 18 או גרסה חדשה יותר
חשבון PolyLingo חינמי ומפתח API

שלב 1: קבל את מפתח ה-API של PolyLingo (5 דקות)

צור חשבון חינמי ב-usepolylingo.com. הרמה החינמית כוללת 100,000 טוקנים בחודש, שזה מספיק כדי לתרגם קובץ locale בגודל בינוני ל-10+ שפות כמה פעמים.

כשתיכנס, עבור לAPI keys בלוח הבקרה ויצור מפתח. תראה את הערך המלא רק פעם אחת, אז העתק אותו מיד.

הוסף אותו לפרויקט שלך כמשתנה סביבה. לעולם אל תתחייב אותו לבקרת גרסאות ואל תחשוף אותו בקוד צד לקוח:

# .env.local
POLYLINGO_API_KEY="pl_your_key_here"

וודא שה-API נגיש לפני שתמשיך:

curl -sS "https://api.usepolylingo.com/v1/health"

אתה אמור לקבל חבילת JSON קטנה עם "status": "ok".

שלב 2: התקן את next-intl והגדר ניתוב (10 דקות)

התקן את הספרייה:

npm install next-intl

צור קובץ i18n.ts בשורש הפרויקט שלך. זה אומר ל-next-intl אילו לוקאלים אתה תומך ואיך לטעון את קובץ ההודעות הנכון לכל בקשה:

// i18n.ts
import { getRequestConfig } from 'next-intl/server'

export const locales = ['en', 'de', 'fr'] as const
export type Locale = (typeof locales)[number]
export const defaultLocale: Locale = 'en'

export default getRequestConfig(async ({ requestLocale }) => {
  let locale = await requestLocale
  if (!locale || !locales.includes(locale as Locale)) {
    locale = defaultLocale
  }
  return {
    locale,
    messages: (await import(`./messages/${locale}.json`)).default,
  }
})

הוסף middleware שמוסיף קידומת לנתיבים עם הלוקאל:

// middleware.ts
import createMiddleware from 'next-intl/middleware'
import { locales, defaultLocale } from './i18n'

export default createMiddleware({
  locales: [...locales],
  defaultLocale,
  localePrefix: 'as-needed',
})

export const config = {
  matcher: ['/((?!api|_next|.*\\..*).*)'],
}

העבר את קבצי הדפים שלך תחת app/[locale]/. עדכן את ה-layout הראשי לקבל את פרמטר הלוקאל ועטוף את הילדים עם NextIntlClientProvider:

// app/[locale]/layout.tsx
import { NextIntlClientProvider } from 'next-intl'
import { getMessages } from 'next-intl/server'

export default async function LocaleLayout({
  children,
  params,
}: {
  children: React.ReactNode
  params: Promise<{ locale: string }>
}) {
  const { locale } = await params
  const messages = await getMessages()
  return (
    <html lang={locale}>
      <body>
        <NextIntlClientProvider messages={messages}>
          {children}
        </NextIntlClientProvider>
      </body>
    </html>
  )
}

שלב 3: חלץ את המחרוזות שלך לקובץ הודעות JSON (10 דקות)

צור תיקיית messages/ בשורש הפרויקט שלך. הוסף קובץ en.json עם מחרוזות המקור שלך. next-intl משתמש במבנה מפתחות מקונן:

{
  "Home": {
    "title": "Welcome",
    "cta": "Get started"
  }
}

עדכן את הדפים שלך להשתמש ב-useTranslations במקום מחרוזות קשיחות:

// app/[locale]/page.tsx
import { useTranslations } from 'next-intl'

export default function HomePage() {
  const t = useTranslations('Home')
  return (
    <main>
      <h1>{t('title')}</h1>
      <button type="button">{t('cta')}</button>
    </main>
  )
}

עכשיו כתוב את סקריפט התרגום. זה קורא את messages/en.json, שולח אותו ל-PolyLingo API עם format: "json", וכותב קובץ פלט אחד לכל לוקאל יעד. הדגל format: "json" אומר ל-API לשמור על מבנה המפתחות ולתרגם רק ערכי מחרוזות — מפתחות מקוננים, מערכים וסוגים שאינם מחרוזות נשארים ללא שינוי.

// scripts/translate-messages.mjs
// הרץ עם: node scripts/translate-messages.mjs

import fs from 'node:fs'
import path from 'node:path'

const API_KEY = process.env.POLYLINGO_API_KEY
const API_URL = (process.env.POLYLINGO_API_URL || 'https://api.usepolylingo.com/v1').replace(/\/$/, '')
const TARGETS = ['de', 'fr'] // הרחב מערך זה להוספת לוקאלים נוספים

const enPath = path.join('messages', 'en.json')
const en = JSON.parse(fs.readFileSync(enPath, 'utf8'))

const res = await fetch(`${API_URL}/translate`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    content: JSON.stringify(en),
    format: 'json',
    targets: TARGETS,
    model: 'standard',
  }),
})

if (!res.ok) {
  const err = await res.text()
  throw new Error(`PolyLingo ${res.status}: ${err}`)
}

const { translations } = await res.json()

for (const locale of TARGETS) {
  const out = path.join('messages', `${locale}.json`)
  fs.writeFileSync(out, JSON.stringify(JSON.parse(translations[locale]), null, 2) + '\n')
  console.log('Wrote', out)
}

הרץ את זה:

node scripts/translate-messages.mjs

אתה אמור לראות פלט כמו:

Wrote messages/de.json
Wrote messages/fr.json

פתח את הקבצים ובדוק אותם. המפתחות שלך יהיו זהים ל-en.json. רק ערכי המחרוזות ישתנו.

שלב 4: בדוק את הנתיבים במהירות (5 דקות)

הפעל את שרת הפיתוח שלך:

npm run dev

בקר בכתובות http://localhost:3000 ו-http://localhost:3000/de. הכותרת והכפתור צריכים להופיע באנגלית ובגרמנית בהתאמה. הוסף לוקאלים נוספים על ידי הרחבת מערך TARGETS בסקריפט ומערך locales ב-i18n.ts, ואז הרץ את הסקריפט שוב.

בדוק את השימוש בטוקנים שלך בלוח הבקרה של PolyLingo תחת Usage. עבור קובץ locale קטן שתורגם לשתי שפות, השתמשת בכמה מאות טוקנים מתוך המנוי החודשי שלך.

לאן להמשיך מכאן

הוסף לוקאלים נוספים. הסקריפט שולח בקשה אחת ללא קשר למספר הפריטים ב-TARGETS. הוספת יפנית, ספרדית וערבית עולה קריאת API אחת, לא שלוש.

שלב אותו ב-CI. הוסף את POLYLINGO_API_KEY כסוד מאגר ב-GitHub Actions והרץ את הסקריפט כחלק מצינור הבנייה שלך. קבצי ה-locale שלך יישארו מסונכרנים אוטומטית בכל פעם ש-en.json משתנה.

תרגם פורמטים אחרים. אותו דפוס סקריפט עובד לדפי תיעוד Markdown (format: "markdown") ותבניות דוא"ל HTML (format: "html"). ה-API שומר על המבנה בכל המקרים.

השתמש בנקודת הקצה batch לפרויקטים גדולים יותר. אם יש לך מספר קבצי JSON נפרדים (אחד לכל אזור תכונה, למשל), POST /translate/batch מקבל עד 100 פריטים בבקשה אחת, כל אחד עם id ו-format משלו.

נסה את זה בחינם

הרמה החינמית של PolyLingo כוללת 100,000 טוקנים בחודש. אין צורך בכרטיס אשראי.

curl -sS -X POST "https://api.usepolylingo.com/v1/translate" \
  -H "Authorization: Bearer $POLYLINGO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "{\"Home\":{\"title\":\"Welcome\",\"cta\":\"Get started\"}}",
    "format": "json",
    "targets": ["de", "fr", "es", "ja"]
  }'

קבל את מפתח ה-API שלך