Skip to content

[Document Translation] Release @azure/ai-translation-document 2.0.0 (2026-03-01 API + DFG migration)#39230

Open
jrjrguo wants to merge 15 commits into
Azure:mainfrom
jrjrguo:document-translation-dfg-migration
Open

[Document Translation] Release @azure/ai-translation-document 2.0.0 (2026-03-01 API + DFG migration)#39230
jrjrguo wants to merge 15 commits into
Azure:mainfrom
jrjrguo:document-translation-dfg-migration

Conversation

@jrjrguo

@jrjrguo jrjrguo commented Jul 10, 2026

Copy link
Copy Markdown
Member

Summary

Releases @azure/ai-translation-document 2.0.0, adding support for the 2026-03-01 service API version. As part of this major release, the package is also migrated from the REST-level client (RLC) package @azure-rest/ai-translation-document to the new modular / data-plane-generated (DFG) design.

Based on spec PR Azure/azure-rest-api-specs#41433, with the .NET PR (Azure/azure-sdk-for-net#60219) as a reference. README + CHANGELOG history are preserved for continuity.

Features added (2026-03-01 API)

  • Added support for the 2026-03-01 service API version.
  • Added deploymentName to TargetInput and DocumentStatus to support translating with a custom translation model.
  • Added deploymentName parameter to single document translation.
  • Added support for translating text within images: translateTextWithinImage on batch and single document translation, plus image-scan fields (imageCharacterDetected, imageCharged, totalImageScansSucceeded, totalImageScansFailed) on DocumentStatus.

Breaking changes

  • Package name changed from @azure-rest/ai-translation-document to @azure/ai-translation-document.
  • The RLC surface (client.path(...).post(...)) is replaced with a modeled client surface exposing two clients (see README for migration examples):
    • DocumentTranslationClient — batch translation (LRO via @azure/core-lro)
    • SingleDocumentTranslationClient — synchronous single-document translation
  • The old RLC package sdk/translation/ai-translation-document-rest is removed.

Spec / codegen fixes surfaced during this work

  • FileFormatType corrected to PascalCase ("Document" | "Glossary") to match service responses.
  • Multipart glossary corrected from a single part containing an array to an array of parts (HttpPart<bytes>[]), fixing multi-glossary uploads.
  • type parameter for getSupportedFormats is now required/positional.

Notes

  • Date boundary handling: JS Date truncates sub-millisecond precision, so createdDateTimeUtc filter end boundaries use a +1ms epsilon in tests (documented inline).
  • LRO usage follows @azure/core-lro v3 semantics: const poller = client.startTranslation(...); await poller.pollUntilDone();

Validation

  • Build, format, lint (0 errors)
  • Live tests: 25 passed / 5 skipped / 0 failed
  • Playback tests: 25 passed / 5 skipped / 0 failed
  • Recordings pushed to Azure/azure-sdk-assets

Jiarui Guo added 9 commits July 8, 2026 11:48
…-translation-document

Regenerate Document Translation SDK from spec PR #41433 (2026-03-01 GA), migrating
from the RLC package @azure-rest/ai-translation-document to the modular (DFG)
package @azure/ai-translation-document.

- Generated modular clients: DocumentTranslationClient, SingleDocumentTranslationClient
- Set version 2.0.0 and carried over README + CHANGELOG history for continuity
- Ported samples (samples-dev) and the integration test suite to the new client API
- Added devDeps @azure/storage-blob and @azure/arm-cognitiveservices
- Build fix: aligned config/tsconfig.src.* include with warp entry points so the
  per-client subpath exports compile

Note: recorded tests need to be re-recorded against live resources; the old
ai-translation-document-rest package removal is a follow-up.
…-translation-document

- Add //sampleConfiguration and publish samples/v2 (TypeScript + JavaScript)
- Carry over sample.env (endpoint/blob/file) and test/sample.env from the RLC package
- Add assets.json for the new recordings path (js/translation/ai-translation-document)
- Add tests.yml for the live/recorded test pipeline
- Update sdk/translation/ci.yml to build/ship the new package artifact
  (azure-ai-translation-document) and drop the old -rest document entry
Superseded by the modular package @azure/ai-translation-document. CI references
to the old package were already updated in the previous commit.
Post-generation lint pass on the modular emitter output:
- Add missing copyright headers to static-helper .mts files
- Convert type-only imports to 'import type' (consistent-type-imports)
- Add emitter-consistent eslint-disable for explicit-module-boundary-types in
  multipartHelpers.ts (matches the disable the emitter already emits in models.ts)

These are emitter-output gaps; the fix must be re-applied after each regeneration
until addressed upstream in @azure-tools/typespec-ts (Azure/typespec-azure).
Lint now reports 0 errors (9 non-blocking generated-code warnings remain).
…pportedFormats

Regenerate from spec commit 8b81ca0 which makes the 'type' query parameter
required on getSupportedFormats for api-version 2026-03-01.

- getSupportedFormats(typeParam, options) — typeParam is now a required argument
- Update all call sites (README snippet, samples, tests) to the positional form
- Remove the 'all formats' test (a request without 'type' is no longer valid; it
  returned 404 in live testing)
- Re-apply post-generation fixes overwritten by regeneration: src tsconfig include
  for subpath exports, multipartHelpers eslint-disable, and eslint --fix headers;
  restore metadata (version 2.0.0, devDeps, //sampleConfiguration, README, sample.env)
  that generate-metadata reset

Build, lint (0 errors), and test type-check all pass.
…tType and multipart glossary fix

Regenerate from spec commit 9b0510f which lands the long-standing fixes:
- FileFormatType values are now PascalCase ("Document" | "Glossary"), matching the
  service response; update all call sites and test assertions accordingly
- Multipart glossary is now modeled as HttpPart<bytes>[] (array of parts), so the
  generated serializer maps each glossary to its own file part instead of sending
  the whole array as one part
- 'type' query parameter remains required on getSupportedFormats

Re-applied the post-generation fixes (src tsconfig include, multipartHelpers
eslint-disable, eslint --fix) and restored metadata reset by generate-metadata.
Build, lint (0 errors), and node/browser test type-check all pass.
- Remove the 'Supported And UnSupported Files' test and its orphaned documents4/
  source-container5 fixture: the 2026-03-01 API now supports image translation, so
  a .jpg is no longer an 'unsupported' file (consistent with other SDKs)
- Fix 'Document Statuses Filter By Created Before': bump the createdDateTimeUtcEnd
  boundaries by 1ms to compensate for JS Date's millisecond truncation of the
  service's sub-millisecond createdDateTimeUtc (the raw value falls just before the
  boundary doc and would exclude it). Matches the .NET GetDocumentStatusesFilterByCreatedBefore
  scenario, which passes because DateTimeOffset preserves the precision.

Live test suite: 25 passed, 5 skipped, 0 failed.
- Fix the blob-endpoint body sanitizer to include the trailing slash, so recorded
  container URLs keep a single slash before the container name and match playback
- Record the live test suite and push recordings to Azure/azure-sdk-assets
- Update assets.json Tag to js/translation/ai-translation-document_c1ade430ec

Playback: 25 passed, 5 skipped, 0 failed.
Copilot AI review requested due to automatic review settings July 10, 2026 06:31
@jrjrguo
jrjrguo requested review from a team, jeremymeng and zhangeugenia as code owners July 10, 2026 06:31
@jrjrguo jrjrguo changed the title [Document Translation] Migrate @azure/ai-translation-document from RLC to modular (DFG) [Document Translation] Release @azure/ai-translation-document 2.0.0 (2026-03-01 API + DFG migration) Jul 10, 2026

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Warning

  • Copilot's review of this pull request may be incomplete because some of the changed files are excluded by your Copilot content exclusion settings. See Excluding content from Copilot for details.

Pull request overview

Migrates Document Translation from the REST-level package to the modular @azure/ai-translation-document 2.0.0 client, including batch LRO and synchronous translation clients.

Changes:

  • Adds modular clients, models, paging, polling, and multipart support.
  • Ports tests, recordings, samples, documentation, and API reports.
  • Replaces the previous RLC package and updates CI configuration.

Reviewed changes

Copilot reviewed 116 out of 125 changed files in this pull request and generated 8 comments.

Show a summary per file
File Description
sdk/translation/ci.yml Updates CI artifact and path.
sdk/translation/ai-translation-document/warp.config.yml Configures package build targets.
sdk/translation/ai-translation-document/vitest.config.ts Configures Node tests.
sdk/translation/ai-translation-document/vitest.browser.config.ts Updates browser test configuration.
sdk/translation/ai-translation-document/tsp-location.yaml Records TypeSpec source.
sdk/translation/ai-translation-document/tsconfig.json Adds project references.
sdk/translation/ai-translation-document/tests.yml Updates test package name.
sdk/translation/ai-translation-document/test/utils/types.ts Updates test containers.
sdk/translation/ai-translation-document/test/utils/setup.ts Updates test provisioning.
sdk/translation/ai-translation-document/test/utils/injectables.ts Moves Vitest context typing.
sdk/translation/ai-translation-document/test/utils/documents.ts Updates test documents.
sdk/translation/ai-translation-document/test/utils/containerHelper.ts Adds storage test helpers.
sdk/translation/ai-translation-document/test/utils/constants.ts Adds test constants.
sdk/translation/ai-translation-document/test/snippets.spec.ts Adds README snippets.
sdk/translation/ai-translation-document/test/sample.env Updates test environment template.
sdk/translation/ai-translation-document/test/public/utils/testHelper.ts Adds modular test helpers.
sdk/translation/ai-translation-document/test/public/utils/StaticAccessTokenCredential.ts Adds static test credential.
sdk/translation/ai-translation-document/test/public/utils/recordedClient.ts Creates recorded modular clients.
sdk/translation/ai-translation-document/test/public/singleDocumentTranslateTest.spec.ts Tests synchronous translation.
sdk/translation/ai-translation-document/test/public/node/translationFilterTest.spec.ts Ports translation filters.
sdk/translation/ai-translation-document/test/public/node/documentFilterTest.spec.ts Ports document filters.
sdk/translation/ai-translation-document/test/public/node/documentTranslationTest.spec.ts Ports batch translation tests.
sdk/translation/ai-translation-document/test/public/node/cancelTranslationTest.spec.ts Ports cancellation tests.
sdk/translation/ai-translation-document/test/public/getSupportedFormatsTest.spec.ts Ports format tests.
sdk/translation/ai-translation-document/src/static-helpers/urlTemplate.ts Adds URI template expansion.
sdk/translation/ai-translation-document/src/static-helpers/serialization/get-binary-stream-response.ts Adds Node stream responses.
sdk/translation/ai-translation-document/src/static-helpers/serialization/get-binary-stream-response-react-native.mts Adds React Native variant.
sdk/translation/ai-translation-document/src/static-helpers/serialization/get-binary-stream-response-browser.mts Adds browser blob responses.
sdk/translation/ai-translation-document/src/static-helpers/pollingHelpers.ts Adds LRO polling support.
sdk/translation/ai-translation-document/src/static-helpers/platform-types.ts Defines Node stream type.
sdk/translation/ai-translation-document/src/static-helpers/platform-types-react-native.mts Defines React Native type.
sdk/translation/ai-translation-document/src/static-helpers/platform-types-browser.mts Defines browser type.
sdk/translation/ai-translation-document/src/static-helpers/pagingHelpers.ts Adds paged iterators.
sdk/translation/ai-translation-document/src/static-helpers/multipartHelpers.ts Adds multipart descriptors.
sdk/translation/ai-translation-document/src/singleDocumentTranslation/singleDocumentTranslationClient.ts Adds synchronous client.
sdk/translation/ai-translation-document/src/singleDocumentTranslation/index.ts Exports synchronous surface.
sdk/translation/ai-translation-document/src/singleDocumentTranslation/api/singleDocumentTranslationContext.ts Creates synchronous context.
sdk/translation/ai-translation-document/src/singleDocumentTranslation/api/options.ts Defines translate options.
sdk/translation/ai-translation-document/src/singleDocumentTranslation/api/operations.ts Implements translate operation.
sdk/translation/ai-translation-document/src/singleDocumentTranslation/api/index.ts Exports synchronous API.
sdk/translation/ai-translation-document/src/models/models.ts Defines generated models.
sdk/translation/ai-translation-document/src/models/index.ts Exports models.
sdk/translation/ai-translation-document/src/logger.ts Configures package logger.
sdk/translation/ai-translation-document/src/index.ts Defines root exports.
sdk/translation/ai-translation-document/src/documentTranslation/restorePollerHelpers.ts Adds poller restoration.
sdk/translation/ai-translation-document/src/documentTranslation/documentTranslationClient.ts Adds batch client.
sdk/translation/ai-translation-document/src/documentTranslation/index.ts Exports batch surface.
sdk/translation/ai-translation-document/src/documentTranslation/api/operations.ts Implements batch operations.
sdk/translation/ai-translation-document/src/documentTranslation/api/options.ts Defines batch options.
sdk/translation/ai-translation-document/src/documentTranslation/api/index.ts Exports batch API.
sdk/translation/ai-translation-document/src/documentTranslation/api/documentTranslationContext.ts Creates batch context.
sdk/translation/ai-translation-document/samples/v2/typescript/tsconfig.json Configures TypeScript samples.
sdk/translation/ai-translation-document/samples/v2/typescript/src/synchronousDocumentTranslation.ts Adds synchronous TS sample.
sdk/translation/ai-translation-document/samples/v2/typescript/src/getSupportedFormats.ts Adds formats TS sample.
sdk/translation/ai-translation-document/samples/v2/typescript/src/batchDocumentTranslation.ts Migrates batch TS sample.
sdk/translation/ai-translation-document/samples/v2/typescript/sample.env Adds TS sample environment.
sdk/translation/ai-translation-document/samples/v2/typescript/README.md Updates TS sample documentation.
sdk/translation/ai-translation-document/samples/v2/typescript/package.json Updates TS sample dependencies.
sdk/translation/ai-translation-document/samples/v2/javascript/synchronousDocumentTranslation.js Adds synchronous JS sample.
sdk/translation/ai-translation-document/samples/v2/javascript/sample.env Adds JS sample environment.
sdk/translation/ai-translation-document/samples/v2/javascript/README.md Updates JS sample documentation.
sdk/translation/ai-translation-document/samples/v2/javascript/package.json Updates JS sample dependencies.
sdk/translation/ai-translation-document/samples/v2/javascript/getSupportedFormats.js Adds formats JS sample.
sdk/translation/ai-translation-document/samples/v2/javascript/batchDocumentTranslation.js Migrates batch JS sample.
sdk/translation/ai-translation-document/samples-dev/synchronousDocumentTranslation.ts Adds canonical synchronous sample.
sdk/translation/ai-translation-document/samples-dev/getSupportedFormats.ts Adds canonical formats sample.
sdk/translation/ai-translation-document/samples-dev/batchDocumentTranslation.ts Migrates canonical batch sample.
sdk/translation/ai-translation-document/sample.env Adds package sample environment.
sdk/translation/ai-translation-document/README.md Documents modular clients.
sdk/translation/ai-translation-document/review/ai-translation-document-singleDocumentTranslation-node.api.md Records synchronous client API.
sdk/translation/ai-translation-document/review/ai-translation-document-singleDocumentTranslation-api-node.api.md Records synchronous operation API.
sdk/translation/ai-translation-document/review/ai-translation-document-models-node.api.md Records model API.
sdk/translation/ai-translation-document/review/ai-translation-document-documentTranslation-node.api.md Records batch client API.
sdk/translation/ai-translation-document/review/ai-translation-document-documentTranslation-api-node.api.md Records batch operation API.
sdk/translation/ai-translation-document/review/ai-translation-document-browser.api.diff.md Records browser API differences.
sdk/translation/ai-translation-document/package.json Defines modular package metadata.
sdk/translation/ai-translation-document/metadata.json Records generation metadata.
sdk/translation/ai-translation-document/LICENSE Adds package license.
sdk/translation/ai-translation-document/eslint.config.mjs Configures linting.
sdk/translation/ai-translation-document/config/tsconfig.test.node.json Configures Node test types.
sdk/translation/ai-translation-document/config/tsconfig.test.browser.json Configures browser test types.
sdk/translation/ai-translation-document/config/tsconfig.src.esm.json Configures ESM build.
sdk/translation/ai-translation-document/config/tsconfig.src.cjs.json Configures CommonJS build.
sdk/translation/ai-translation-document/config/tsconfig.src.browser.json Configures browser build.
sdk/translation/ai-translation-document/config/tsconfig.snippets.json Configures snippet checking.
sdk/translation/ai-translation-document/config/tsconfig.lint.json Configures lint type checking.
sdk/translation/ai-translation-document/CHANGELOG.md Documents 2.0 migration.
sdk/translation/ai-translation-document/assets.json Records test assets.
sdk/translation/ai-translation-document/api-extractor.json Configures API extraction.
sdk/translation/ai-translation-document-rest/warp.config.yml Removes old build config.
sdk/translation/ai-translation-document-rest/tsp-location.yaml Removes old TypeSpec metadata.
sdk/translation/ai-translation-document-rest/tsconfig.test.node.json Removes old Node test config.
sdk/translation/ai-translation-document-rest/tsconfig.test.json Removes old test references.
sdk/translation/ai-translation-document-rest/tsconfig.src.json Removes old source config.
sdk/translation/ai-translation-document-rest/tsconfig.snippets.json Removes old snippet config.
sdk/translation/ai-translation-document-rest/tsconfig.samples.json Removes old sample config.
sdk/translation/ai-translation-document-rest/tsconfig.json Removes old project config.
sdk/translation/ai-translation-document-rest/tsconfig.browser.config.json Removes old browser config.
sdk/translation/ai-translation-document-rest/test/public/utils/testHelper.ts Removes RLC test helpers.
sdk/translation/ai-translation-document-rest/test/public/singleDocumentTranslateTest.spec.ts Removes RLC translate tests.
sdk/translation/ai-translation-document-rest/test/public/node/documentFilterTest.spec.ts Removes RLC filter tests.
sdk/translation/ai-translation-document-rest/src/responses.ts Removes RLC responses.
sdk/translation/ai-translation-document-rest/src/pollingHelper.ts Removes RLC polling helper.
sdk/translation/ai-translation-document-rest/src/paginateHelper.ts Removes RLC paging helper.
sdk/translation/ai-translation-document-rest/src/outputModels.ts Removes RLC output models.
sdk/translation/ai-translation-document-rest/src/models.ts Removes RLC models.
sdk/translation/ai-translation-document-rest/src/isUnexpected.ts Removes RLC response checks.
sdk/translation/ai-translation-document-rest/src/index.ts Removes RLC exports.
sdk/translation/ai-translation-document-rest/src/documentTranslationClient.ts Removes RLC client factory.
sdk/translation/ai-translation-document-rest/samples/v1/typescript/tsconfig.json Removes old TS sample config.
sdk/translation/ai-translation-document-rest/samples/v1/typescript/src/synchronousDocumentTranslation.ts Removes old synchronous TS sample.
sdk/translation/ai-translation-document-rest/samples/v1/typescript/src/getSupportedFormats.ts Removes old formats TS sample.
sdk/translation/ai-translation-document-rest/samples/v1/javascript/synchronousDocumentTranslation.js Removes old synchronous JS sample.
sdk/translation/ai-translation-document-rest/samples/v1/javascript/getSupportedFormats.js Removes old formats JS sample.
sdk/translation/ai-translation-document-rest/samples-dev/synchronousDocumentTranslation.ts Removes old canonical sample.
sdk/translation/ai-translation-document-rest/samples-dev/getSupportedFormats.ts Removes old canonical sample.
sdk/translation/ai-translation-document-rest/package.json Removes old package manifest.
sdk/translation/ai-translation-document-rest/eslint.config.mjs Removes old lint config.
sdk/translation/ai-translation-document-rest/assets.json Removes old test assets.
sdk/translation/ai-translation-document-rest/api-extractor.json Removes old API config.
pnpm-lock.yaml Lockfile updated; contents excluded.
Files excluded by content exclusion policy (1)
  • pnpm-lock.yaml
Comments suppressed due to low confidence (1)

sdk/translation/ai-translation-document/samples-dev/batchDocumentTranslation.ts:80

  • This canonical sample is published to both ESM-looking TypeScript and CommonJS JavaScript outputs, but import.meta is invalid in the generated CommonJS sample (and the TypeScript sample package has no type: module). The published batch sample therefore fails to parse/build. Use module-neutral output-directory logic here and regenerate both sample trees with the sample publisher.

Comment thread sdk/translation/ai-translation-document/src/static-helpers/multipartHelpers.ts Outdated
Comment on lines +113 to +116
result =
nextLinkMethod === "POST"
? await client.pathUnchecked(resolvedPageLink).post()
: await client.pathUnchecked(resolvedPageLink).get();

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Acknowledged, but leaving as-is intentionally. This is a static helper emitted by the code generator. The newer emitter (see sdk/ai/ai-projects) only forwards operation-specific static headers via nextPageRequestOptions; it does not propagate the caller's abortSignal/tracing to continuation pages either. Hand-editing this generated file would create customization drift without fully addressing the concern, so this is best resolved by an emitter update rather than a local patch. It is not causing a CI failure.

Comment thread sdk/translation/ai-translation-document/package.json Outdated
Comment thread sdk/translation/ai-translation-document/package.json
Jiarui Guo added 2 commits July 12, 2026 17:09
- Fix stale pnpm-lock.yaml (remove deleted ai-translation-document-rest importer)
- Move node-only tests into test/public/node/ (no browser recordings) to fix browser CI
- Add [apiref] links + apiRefLink sample config (fix Verify Links)
- Correct user-agent version 1.0.0-beta.1 -> 2.0.0 in both client contexts
- Fix multipart descriptor detection for empty-string contents
- Fix documentFilter test to use orderby instead of statuses
- Add CHANGELOG.md to package files allowlist
- multipartHelpers: accept unknown input so generated models.ts (x: unknown) compiles (fixes TS2345)
- Format eslint.config.mjs with prettier (fixes check-format)
- Add new-package learn/npm URLs to eng/ignore-links.txt (fixes Verify Links 404s)
@jrjrguo
jrjrguo requested a review from a team as a code owner July 13, 2026 00:24
jrjrguo and others added 4 commits July 12, 2026 17:53
- review/ai-translation-document-browser.api.diff.md: regenerate via extract-api (committed copy had whitespace/trailing-newline drift, failing the API check)
- documentFilterTest: revert orderby -> statuses; the existing recording was captured with the statuses query param, so orderby fails playback matching (would require re-recording)
…cord

Corrects the test to pass the ordering expression via the orderby query parameter (was incorrectly using statuses). Re-recorded the single test against live resources; assets tag updated to js/translation/ai-translation-document_c3242c2151.
All recorded tests are Node-only and live under test/**/node/, so the browser run has no matching specs. CI invokes 'vitest -c vitest.browser.config.ts' (no run subcommand), which exits code 1 on an empty suite. Set passWithNoTests so the empty browser suite exits 0; browser tests added later will run automatically.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants