API reference

Endpoint: POST /graphql · Metadata: GET /api/info

Quick start

Opening /graphql in the browser shows GraphiQL — paste a query and hit Run. A bare visit without a query returns Must provide query string (normal GraphQL behaviour).

Try in the browser (GET)

List languages:

/graphql?query={ languages { name langCode } }

Hello, World → 你好，世界 (POST)

curl -X POST https://translatial.vercel.app/graphql \
  -H "Content-Type: application/json" \
  -d '{"query":"mutation { translateWords(content: \"Hello, World\", targetLanguages: [\"zh-cn\", \"my\", \"ja\"]) { result { targetLanguage { name langCode } content } } }"}'

Mock mode (default without DEEPL_API_KEY) returns real demo phrases for Hello and Hello, World. Other text is prefixed with the language name.

List languages (POST)

curl -X POST https://translatial.vercel.app/graphql \
  -H "Content-Type: application/json" \
  -d '{"query":"{ languages { name langCode } }"}'

Query — languages

Returns the supported language catalog (stable list, no external scrape).

{
  languages {
    name
    langCode
  }
}

Mutation — translateWords

Translate content into each code in targetLanguages.

mutation {
  translateWords(
    content: "Hello, World"
    targetLanguages: ["zh-cn", "my", "ja"]
  ) {
    result {
      targetLanguage { name langCode }
      content
      pronunciation
    }
  }
}

Example response (mock mode): 你好，世界 for zh-cn.

Environment variables

• TRANSLATION_MODE=mock — prefix translations (default when no DeepL key)
• TRANSLATION_MODE=live — require DEEPL_API_KEY
• DEEPL_API_KEY — DeepL API key for production translations
• DEEPL_API_URL — optional; defaults to DeepL free API

Local development

npm install
npm test
npx vercel dev

GraphiQL is enabled when NODE_ENV is not production. Legacy Python Flask implementation is preserved in the repo root for reference.

History

v1 shipped on Ainize with Flask + Graphene + googletrans. v2 (Eternal Flame) is TypeScript on Vercel — same GraphQL shape, maintainable dependencies, and optional DeepL instead of scraping Google Translate.