This document provides definitions and best practices related to the specification of manifest files and similar document formats on the Web.

Some specifications on the Web deal with defining sets of files or resources to be consumed together. A common design pattern is to provide a manifest or configuration file that defines which resources are available and how various resources should be used or to provide various kinds of metadata about a collection of resources. This document provides definitions and best practices related to the specification of manifest files and similar document formats on the Web.

Introduction

Some specifications on the Web deal with defining sets of files or resources to be consumed together. A common design pattern is to provide a manifest or configuration file that defines which resources are available and how various resources should be used or to provide various kinds of metadata about a collection of resources.

Some examples of specifications like this include Webapp [[APPMANIFEST]], Miniapp [[MINIAPP-MANIFEST]], and ePub [[EPUB-33]].

Manifest file formats usually contain syntactic or user-supplied values that are not localizable. But most manifest file formats also contain at least some localizable content fields. A specification that defines a manifest file format that includes localizable content values needs to provide a means for users to localize the manifest into different languages. This document covers the pros and cons of common designs, along with some best practices related to building and managing manifests.

These (and many other) best practices, along with links to supporting materials, can also be found in the Internationalization Best Practices for Spec Developers [[INTERNATIONAL-SPECS]]. In addition to the best practices found here, additional best practices relating to language metadata on the Web can be found in [[STRING-META]]. Core terminology can also be found in the Internationalization Glossary [[I18N-GLOSSARY]].

Requirements and Use Cases

There are different ways that manifest files might be used on the Web and these affect the choice of manifest localization strategy.

Packaged Manifest. Some manifests are packaged with other files to form an application or document. Since the manifest is generally consumed as part of the larger set of content and the content is downloaded as a single unit, localization strategies that are modular, consisting of multiple files, are easier to use.

Shorthand Description Manifest. Other manifests are meant to be used as a shorthand description of the document or application. Manifests like this are often downloaded by the client: retrieving multiple files has latency, size, and storage implications that point toward fewer files or less modular approaches.

Another consideration is the language negotiation strategy employed by the specification.

Bear in mind that modern operating environments support quite extensive sets of available locales and that application owners often wish to satisfy diverse audiences with a single localized application or document. While examples in specifications necessarily are constrained to maybe three or four locales, actual applications with 50 or more specific locales are not uncommon.

Common Approaches

There are several common approaches to creating localized manifests. Each offers certain advantages (and suffers from certain drawbacks):

Unitary Manifest Files

A unitary manifest approach provides for localization by defining localizable fields using an array of language values.

The advantages of a unitary manifest include:

  1. The manifest is a single file, allowing for ease of downloading.
  2. It is easier to ensure that the correct version of the resources in every language are being used.
  3. Language defaulting may be easier to manage.

There are also disadvantages to this approach:

  1. If the manifest is rendered into many languages, the file's size may grow disproportionately.
  2. Localization processes are generally optimized to create files that are copies of the original, only with the language-bearing materials replaced. Creating, managing, and synchronizing localization in a highly multilingual file may be more complex than using separate files per language. Generating the manifest via scripts or tooling is one approach to managing this complexity.

Unitary manifests work best with smaller source files with a limited number of localizable content fields and/or a limited number of languages. Most unitary manifests define some type of “language indexing” scheme (such as found in [[JSON-LD]]) to perform the actual selection.

Language or Locale-specific Manifest Files

Locale-specific manifests create a separate file for each supported language or locale. Usually the specification will choose either a path or filename based organizational scheme for allocating and finding the manifest files.

The advantages of locale-specific manifests include:

  1. Managing the creation or addition of locales is generally easier. Localization processes are generally optimized for “creating a localized copy” of a given source file.

The disadvantages include:

  1. Even simple locale fallback chains can require the client to search for or retrieve multiple files.
  2. Because the files are separate, versioning of the content must be rigorously controlled.
  3. It may be necessary to test many more variations to ensure proper operation.

Hybrid Approaches

A common compromise is to have a central manifest file that contains most or all of the non-localizable content, coupled with separate files that contains the localizable content. In some cases, the central manifest file contains defaults for the localizable content. The central manifest might also contain a directory or list of available locales (or the URL of language-specific manifests) so that clients only need to try to retrieve localized files that are actually available.

Path versus File Name Localization

Some manifests opt to store localized variants of the manifest using modification of the path. Others prefer to modify the file name.

Path-based storage has the advantage that multiple files can be localized together. For example, the localized manifest can include a localized icon, logo, stylesheet, README, and terms-of-service file together with the manifest. New languages can be added by adding a new directory.

Path-based systems have the disadvantage that the filenames are generally “all the same” and the contents of a given file is not obvious from the filename—only by its location in the application hierarchy.

Filename-based storage has the advantage that the contents of the file is obvious from the filename and managing files can sometimes be easier in this regard.

Other Considerations

Note that manifest localization does not remove the need for the string content in a manifest to provide language and direction metadata for each separate data value. The manifest file can define a file-wide default for language and direction, but specific files should be able to override either value. See [[STRING-META]] for more information.

Some manifests allow for "sparse population" of values in the localized file. For example, the en-US (English, United States) file might only contain one or two US-specific values, relying on the en (English) file for most of its content. Specifications need to be explicit about whether sparse population is allowed and how it works to avoid misconfiguration errors or missing translations.