Copyright © 2021 W3C® (MIT, ERCIM, Keio, Beihang). W3C liability, trademark and permissive document license rules apply.
This document provides definitions and best practices related to the specification of manifest files and similar document formats on the Web.
This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at https://www.w3.org/TR/.
The Working Group expects this to become a Working Group Note.
This document was published by the Internationalization Working Group as a First Public Working Draft.
GitHub Issues are preferred for discussion of this specification.
Publication as a First Public Working Draft does not imply endorsement by the W3C Membership.
This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.
This document was produced by a group operating under the 1 August 2017 W3C Patent Policy. The group does not expect this document to become a W3C Recommendation. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.
This document is governed by the 15 September 2020 W3C Process Document.
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].
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.
There are several common approaches to creating localized manifests. Each offers certain advantages (and suffers from certain drawbacks):
A unitary manifest approach provides for localization by defining localizable fields using an array of language values.
The advantages of a unitary manifest include:
There are also disadvantages to this approach:
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.
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:
The disadvantages include:
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.
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.
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.