Choose a multilingual headless CMS by its translation model, per-language publishing behavior, and handling of missing translations. genko.me keeps language versions under a shared content ID and field structure, while managing values and publication states independently. For a bilingual blog, that lets you connect translations of the same article, release them at different times, and implement language URLs and hreflang in your frontend.
This article is written by the team behind genko.me. Product behavior and the external references below were checked on October 20, 2026.
Field-level vs entry-level localization
Field-level localization stores different language values within an entry's fields. Entry-level localization uses separate entries for different languages and records how those translations relate to one another. These labels describe modeling approaches; they do not fully specify a product's publication or ID behavior.
Model | Useful for | Questions to settle early |
|---|---|---|
Field-level | Product data with many shared attributes | Which fields are localized, and which values stay shared? |
Entry-level | Editorial content with region-specific structure | How are translations linked and shared values maintained? |
Shared ID with language versions | The same article published in several languages | How are copied values, publication states, and missing versions handled? |
A product catalog with shared identifiers and translated descriptions has different needs from a publication that changes examples and section structure by region. Start with an actual content item and map which parts need translation, independent editing, or shared updates.
Also distinguish the editing interface's language from content localization. An English administration interface does not tell you whether articles can have independently published Japanese versions.
Contentful, Sanity, and genko.me localization compared
CMS | Verified approach | A useful reason to evaluate it |
|---|---|---|
Contentful | Localized fields and configurable fallback locales | Detailed control of translated fields and alternative languages |
Sanity | Field-level and document-level models | A translation model adapted to custom content structures |
genko.me | Shared content ID and fields with separate language values and states | Publishing translations of the same blog article independently |
Contentful lets you enable localization on selected fields and configure fallback chains for missing translated values. Consider it when you need granular choices about localized fields and substitute languages. Contentful localization documentation
Sanity documents both models and supporting plugins. Its guide describes field-level content as languages within one document, while document-level localization permits independent language publication. That flexibility is useful when the content model itself needs customization. Sanity localization documentation
genko.me's native workflow uses language versions within one API, rather than a separate API for every language. The content ID and field structure stay shared. This makes matching article translations straightforward, but copied values are not automatically synchronized when the original changes.
How to set up multilingual content in genko.me
Have the owner set the workspace's main and additional languages.
Enable multilingual content on the relevant API.
Copy a main-language article into an additional-language draft.
Translate the values and check that language's preview.
Publish each version when it is ready.
Request the intended language from the website using
lang.
Free allows one additional language; Plus and Pro do not impose a count limit on additional languages. A Japanese-and-English blog therefore fits the language count on Free. Language-version content still consumes the content storage allowance, so check the other plan limits as well.
Adding a language does not generate translated entries. Copying creates a starting point at that moment, not a live synchronization relationship. Assign someone to propagate later corrections, such as a revised release date or a changed product name, to existing translations.
The multilingual content guide covers the administration workflow and links to settings, previews, and language-specific imports.
Fetch a published English article through the REST API
Assume you have a list API named blog, a published English version, and an API key allowed to read that API. Set the key in your server environment and replace the workspace and article identifiers:
curl --get 'https://api.genko.me/v1/your-workspace/blog/abcDEF123456' \ -H "X-API-KEY: ${GENKO_API_KEY}" \ --data-urlencode 'lang=en' \ --data-urlencode 'include=_langs'For a single entry, an English version that is missing or unpublished returns 404 by default. Omitting lang requests the main language. Do not assume that a missing translation will silently turn into a main-language article.
The include=_langs option adds information about the language actually returned and the available published languages:
{ "_langs": { "current": "en", "available": ["ja", "en"] } }This is useful for showing a language switch only when the destination is available. The delivery API reference and query specification describe the full request behavior.
Fetch localized article lists with the SDK
This server-side example assumes the SDK is installed and blog has a text field called title. The manual API definition describes fetching; it does not create an API in the CMS.
import { createGenko, listApi } from "@genko-me/sdk";
const apiKey = process.env.GENKO_API_KEY;if (!apiKey) throw new Error("GENKO_API_KEY is required");
const genko = createGenko({ workspace: "your-workspace", apiKey, apis: { blog: listApi<{ title: string }>() },});
const { contents } = await genko.apis.blog.list({ lang: "en", include: ["_langs"],});
for (const post of contents) { console.log(post.id, post.title, post._langs?.available);}The list requests articles with published English versions. In an existing project, reuse the CLI-generated client rather than maintaining a duplicate definition solely for localization.
To substitute the published main language when the requested version is unavailable, explicitly add langFallback: true in the SDK or lang_fallback=true in HTTP. Fallback is disabled by default. Check the SDK query guide for the details.
Should missing translations fall back or return 404?
This is a product decision as well as a technical setting. A catalog may prefer to show an original-language description rather than hide a product. A publication offering an English edition may prefer to list only completed English articles.
Define the rule before building navigation. If fallback is enabled, inspect the actual returned language rather than treating the requested language as proof of the response language. If fallback is disabled, make the absence understandable in the application and avoid linking readers to translations that are not available.
Test both states with real content: one article available in both languages and another whose additional-language version remains a draft. A fully translated test dataset will not reveal missing-version behavior.
Plan language URLs and hreflang in the frontend
A CMS language version is not itself a public page URL. For example, you can map the Japanese version to /articles/example and the English version to /en/articles/example. The shared content ID identifies corresponding articles. If you translate slugs, preserve the mapping from each language's slug to the same content identity.
Google's guidance calls for each language page to list itself and its alternatives with fully qualified URLs, and for corresponding pages to link back to each other. Google localized-page guidance
For a published Japanese-and-English pair, output this set in each page's head:
<link rel="alternate" hreflang="ja" href="https://example.com/articles/example" /><link rel="alternate" hreflang="en" href="https://example.com/en/articles/example" />These are frontend outputs, not CMS settings. Use published-language information such as _langs.available to keep language switches and alternate-page links aligned. Avoid mechanically advertising a translation URL before that version has been published.
Hreflang does not guarantee search rankings or citations in AI search. Its role here is to describe the relationship between language versions. The article content and the availability of each destination still need independent review.
Maintain translations after publication
Each language has its own scheduled publication and end dates, preview key, and history. A published Japanese article does not make its English draft readable through normal delivery.
Pending changes on published content are also language-specific. Correcting one version does not mean the other versions have received the same correction. Maintain a simple review list identifying translations that need to catch up with the source article.
If webhooks refresh your frontend, language-version events include a top-level lang. Use that information when choosing which language URL to refresh or rebuild. Test the path from translated publication through to the visible page rather than checking the CMS state alone.
Removing an additional language from the workspace deletes that language's content and history. Review exports and retention needs before removing a language as a cleanup operation.
AI can help prepare translations, but review the saved body, internal links, and regional details before release. For language-version editing through MCP, see publishing CMS content from Claude Code. For the cost of starting a bilingual site, see the free headless CMS comparison.
FAQ
Do I need a separate CMS API for each language?
Not with genko.me's multilingual workflow. A single API holds language versions under the same content ID, after multilingual content has been enabled for that API.
Does an untranslated article automatically fall back to Japanese?
No. Fallback is disabled by default. Use HTTP lang_fallback=true or SDK langFallback: true to request the published main language when the requested version is unavailable.
Can I build a bilingual blog on the free plan?
As of October 2026, Free supports the main language plus one additional language. Content and media capacity and the other plan conditions still apply.
Does the CMS automatically output hreflang?
In this architecture, your frontend generates hreflang from the public language URLs. Creating a translation in the CMS does not configure your page's head by itself.
Sources
Checked October 20, 2026.