feat(cli): support registering translated API definitions in docs publish

[dsinghvi]

Description

Extends the docs publish flow to support registering translated API definitions alongside translated pages. Users can place translated API definition JSON files in translations/<lang>/apis/<api-name>.json and they will be included in the translation registration request to FDR.

Companion PR: https://github.com/fern-api/fern-platform/pull/10196 (FDR backend changes to accept and merge translated API definitions)

Changes Made

• ParsedDocsConfiguration (packages/cli/configuration/): Added translationApiDefinitions field — Record<string, Record<string, unknown>> | undefined — mapping locale → { apiName → JSON definition }
• parseDocsConfiguration.ts (packages/cli/configuration-loader/): Added loadTranslationApiDefinitions() function that scans translations/<lang>/apis/*.json directories and loads translated API definition JSON files
• DocsDefinitionResolver (packages/cli/docs-resolver/): Added getTranslationApiDefinitions() getter to expose loaded translation API definitions
• publishDocs.ts (packages/cli/generation/remote-generation/remote-workspace-runner/): Updated translation registration to include apiDefinitions in the request body when available, with logging of included API definition names
• Added changelog entry for the new feature

Testing

• TypeScript compilation passes for all modified packages (45/45 tasks successful)
• Biome lint/check passes on all modified files
• Pre-commit hooks pass

Link to Devin session: https://app.devin.ai/sessions/36455db2d89641e3b8dd32c39a792643
Requested by: @dsinghvi

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment and CI monitoring

[claude]

Claude Code Review

This repository is configured for manual code reviews. Comment @claude review to trigger a review and subscribe this PR to future pushes, or @claude review once for a one-time review.

_{Tip: disable this comment in your organization's Code Review settings.}

[github-actions]

Docs Generation Benchmark Results

Comparing PR branch against median of 5 nightly run(s) on main (latest: 2026-04-23T04:59:11Z).

Fixture	main	PR	Delta
docs	301.0s (n=5)	313.8s (35 versions)	+12.8s (+4.3%)

Docs generation runs fern generate --docs --preview end-to-end against the benchmark fixture with 35 API versions (each version: markdown processing + OpenAPI-to-IR + FDR upload).
Delta is computed against the nightly baseline on main.
Baseline from nightly run(s) on main (latest: 2026-04-23T04:59:11Z). Trigger benchmark-baseline to refresh.
Last updated: 2026-04-28 18:37 UTC

[github-actions]

SDK Generation Benchmark Results

Comparing PR branch against median of 5 nightly run(s) on main (latest: 2026-04-23T04:59:11Z).

Full benchmark table (click to expand)

Generator	Spec	main (generator)	main (E2E)	PR (generator)	Delta
csharp-sdk	square	56s (n=5)	86s (n=5)	23s	-33s (-58.9%)
go-sdk	square	115s (n=5)	132s (n=5)	22s	-93s (-80.9%)
java-sdk	square	179s (n=5)	207s (n=5)	85s	-94s (-52.5%)
php-sdk	square	43s (n=5)	66s (n=5)	22s	-21s (-48.8%)
python-sdk	square	115s (n=5)	223s (n=5)	21s	-94s (-81.7%)
ruby-sdk-v2	square	130s (n=5)	159s (n=5)	21s	-109s (-83.8%)
rust-sdk	square	166s (n=5)	163s (n=5)	22s	-144s (-86.7%)
swift-sdk	square	41s (n=5)	290s (n=5)	22s	-19s (-46.3%)
ts-sdk	square	74s (n=5)	86s (n=5)	23s	-51s (-68.9%)

main (generator): generator-only time via --skip-scripts (includes Docker image build, container startup, IR parsing, and code generation — this is the same Docker-based flow customers use via fern generate). main (E2E): full customer-observable time including build/test scripts (nightly baseline, informational). Delta is computed against generator-only baseline.
⚠️ = generation exited with a non-zero exit code (timing may not reflect a successful run).
Baseline from nightly runs on main (latest: 2026-04-23T04:59:11Z). Trigger benchmark-baseline to refresh.
Last updated: 2026-04-28 18:34 UTC

[graphite-app]

The translation registration logic only checks for translationPages but not translationApiDefinitions. If a user provides only translated API definitions without translated pages, the entire registration block is skipped and API definitions are never registered.

Fix:

if ((translationPages != null && Object.keys(translationPages).length > 0) || 
    (translationApiDefinitions != null && Object.keys(translationApiDefinitions).length > 0)) {
    const totalLocales = new Set([
        ...Object.keys(translationPages ?? {}),
        ...Object.keys(translationApiDefinitions ?? {})
    ]).size;
    context.logger.info(`Registering translations for ${totalLocales} locale(s)...`);

Suggested change

	const translationDomain = preview ? urlToOutput : domain;
	if (translationPages != null && Object.keys(translationPages).length > 0) {
	const translationDomain = preview ? urlToOutput : domain;
	if ((translationPages != null && Object.keys(translationPages).length > 0) ||
	(translationApiDefinitions != null && Object.keys(translationApiDefinitions).length > 0)) {
	const totalLocales = new Set([
	...Object.keys(translationPages ?? {}),
	...Object.keys(translationApiDefinitions ?? {})
	]).size;
	context.logger.info(`Registering translations for ${totalLocales} locale(s)...`);

Spotted by Graphite



Is this helpful? React 👍 or 👎 to let us know.