---
search:
  exclude: true
changelog:
  category: Release
  version: 0.2.0
date: '2026-10-15T12:02:28Z'
seo:
  description: >-
    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…
title: v0.2.0
type: changelog
---
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 |

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

```json
{
  "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](https://app-translations.thebuilder.dk/delivery-api#i18next) 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