v0.2.0

The delivery API can now serve several namespaces, or all of them, in one request, and its formats are named after the message syntax they check rather than after a library. Both change what existing integrations send, so read Breaking changes before upgrading.

Breaking changes

Delivery formats are named by message syntax

The format values were named after next-intl and i18next, but both always returned the same JSON. What format actually checks is the syntax inside each message, and ICU is read by react-intl, FormatJS, Lingui and messageformat as well as next-intl. The values now say that, and match the source’s own Message syntax setting.

Before	After
`format=next-intl`	`format=icu`, or leave `format` out
`format=i18next-v4`	`format=i18next`, or leave `format` out

The old values are not kept as aliases: they get 400 with the new ones in the message. Update the delivery URLs your application fetches before you upgrade the site, or at the same time.

`format` no longer defaults to next-intl

A request without format used to be checked as ICU, so an i18next namespace answered 409 unless you asked for i18next-v4. Now a request without format gets the messages in whatever syntax they are written in, and Umbraco refuses only a response that would mix ICU and i18next.

If you relied on the default to keep i18next messages out of an ICU application, send format=icu.

C#: `TranslationOutputFormat` members are renamed

TranslationOutputFormat.NextIntl is now TranslationOutputFormat.Icu, and TranslationOutputFormat.I18NextV4 is now TranslationOutputFormat.I18Next. Their JSON values are icu and i18next. Only code that references the enum is affected.

Several namespaces, or all of them

namespace is now optional, and can be repeated.

Request	Response
`namespace=website`	The namespace’s messages at the top level, unchanged from 0.1
`namespace=checkout&namespace=website`	Each namespace as a top-level key holding its own messages
no `namespace`	Every namespace in the language, keyed the same way

GET /umbraco/delivery/api/v1/app-translations/all?locale=da-DK

{
  "checkout": { "pay": "Betal nu" },
  "website": { "greeting": "Hej {name}, godt at se dig igen!" }
}

The order you name namespaces in does not matter, and each comes back under the spelling you used.
A namespace that does not exist is left out. From overrides, so is a namespace nobody edited.
Up to 20 namespaces per request.
Repeat the parameter rather than separating names with commas: namespace=checkout,website gets 400 unless a namespace really has that name.
A request without namespace used to get 400. It now gets every namespace.

For i18next, Umbraco’s namespaces can map straight onto i18next’s: fetch every namespace once and add each with addResourceBundle. The Delivery API guide has the example.

Settings

Settings > App translations offers All namespaces in the URL builder, for a language whose namespaces can all be served in one format.
The format choices read ICU MessageFormat and i18next JSON v4.
The source editor explains that a fixed namespace is the name your application fetches its messages by, not a key in its file.

For code that implements the repository

ITranslationMessageRepository gains an overload, GetOutputMessagesAsync(string locale, IReadOnlyCollection<string> namespaces, CancellationToken). Its default implementation calls the existing single-namespace method once per namespace, so an existing implementation keeps serving requests that name their namespaces. A request for every namespace needs the overload implemented; the default throws NotSupportedException.

Documentation

API reference pages for the overrides, all and sync endpoints, with parameters, responses and examples.
The Delivery API guide explains what overrides and all return, how namespaces shape the response, and which libraries read which message syntax.
A refreshed landing page.

Dependencies

Raised minimum versions: Microsoft.Extensions.AI.Abstractions 10.11.0, Microsoft.Extensions.Http 10.0.13, MailKit and MimeKit 4.18.1, and MessagePack 3.1.12. Supported versions are unchanged: Umbraco 17.1 and later, Umbraco 18 included, on .NET 10.

What’s Changed

feat(docs): particle hero on the landing page by @thebuilder in https://github.com/thebuilder/umbraco-app-translations/pull/56
Family README header and dependency updates by @thebuilder in https://github.com/thebuilder/umbraco-app-translations/pull/57
Docs: API reference pages, wider prose and highlighted landing code by @thebuilder in https://github.com/thebuilder/umbraco-app-translations/pull/58
Delivery API: several namespaces or all of them, and formats named by syntax by @thebuilder in https://github.com/thebuilder/umbraco-app-translations/pull/59

Full Changelog: https://github.com/thebuilder/umbraco-app-translations/compare/v0.1.1...v0.2.0