Support for Multi-language Render Templates

[vishwa-vyom]

Context / Problem
In our wallet implementation, we encountered challenges around multi-language support for render templates. The current spec is not explicit about how to associate a render template with a specific language.

We implemented a design where multiple renderMethod objects are configured (one per language). The wallet then provides a UI for users to switch between languages. While this works, it’s unclear if this approach aligns with the spec.

A key UX challenge is how wallets should determine which template to show first. Ideally, the wallet should display the user’s preferred language (based on device or wallet settings) by default, and then allow switching to alternate languages. The current spec doesn’t define how templates are linked to a language, making this prioritization difficult.

Example
We tested this with a credential (farmer VC) that has three languages. Each language uses a separate SVG render template, and the wallet slides between them.

Questions / Proposal

Should the spec explicitly support a way to indicate the language of each render template?

Would it make sense to add a contentLanguage property (mirroring the Content-Language HTTP header) to the template object, so wallets can:

• Automatically detect the language of a template

• Prioritize showing the user’s preferred language first

• Provide fallbacks when the preferred language is not available

Are there best practices for ordering or fallback behavior in multi-language scenarios?

[dlongley]

We could potentially add an optional property to a template value in TemplateRenderMethod where the associated language could be expressed. Then multiple template values could also be expressed, if desired, where the rendering software could make a choice on what to use/fetch based on the template properties (such as language).

It seems like this would be a relatively minor addition to the context and data model -- with complexity added for simple rendering software today that will have to know how to pick / default to a particular template value when there is more than one.

I would expect this information could still be expressed directly in the VC or by reference (as in the different examples), fitting into the existing approaches. Rendering software (e.g., within a wallet) could then fetch the information as needed and make a choice based on the available languages and the user's preferred language.

[sanchi-singh24]

@dlongley @vishwa-vyom Just one more question to add here!

When multiple renderMethod objects are defined (one per language), the wallet has no deterministic way to know which one to prioritize without external metadata.

Even adding a lightweight contentLanguage (or similar) property in TemplateRenderMethod would allow wallets to:

1. "Match the credential template to the holder’s device locale".
2. "Provide predictable fallback logic (e.g., en → hi → default)".
3. "Avoid awkward defaults (like showing the first template by JSON order)".

Would it make sense to suggest a language negotiation pattern similar to Accept-Language in HTTP or lang in HTML, so wallets can make deterministic choices while remaining backward compatible?

Could the spec define a fallback rule or allow a "default": true flag for issuers?

[vishwa-vyom]

Thanks @dlongley — that clarifies it.

We were considering using multiple renderMethod entries because the current spec mentions that one or more render methods MAY be present, and for TemplateRenderMethod, the template property can be a string or a map.

Given that, it felt natural to express one render method per language variant.

However, if the template property itself could support an array of template values — each optionally carrying a language field — that actually feels much cleaner and more intuitive for facilitating language-specific templates.

This would also make the intent explicit (a single render method with multiple localized templates) and avoid overloading multiple renderMethod entries for what’s essentially the same rendering type.

I think your suggestion fits nicely with that direction.
It would be great if the spec could note that template MAY be an array and include an example similar to this:

"renderMethod": {
    "type": "TemplateRenderMethod",
    "renderSuite": "svg-mustache",
    "name": "Localized SVG degree view",
    "description": "SVG template in multiple languages for rendering the degree credential.",
    "renderProperty": [
      "/issuer",
      "/validFrom",
      "/credentialSubject/degree/name"
    ],
    "template": [
      {
        "id": "https://example.edu/templates/degree-en.svg",
        "mediaType": "image/svg+xml",
        "contentLanguage": "en",
        "digestMultibase": "zQmerWC85Wg6wFl9znFCwYxApG270iEu5h6JqWAPdhyxz2dR"
      },
      {
        "id": "https://example.edu/templates/degree-fr.svg",
        "mediaType": "image/svg+xml",
        "contentLanguage": "fr",
        "digestMultibase": "zQmXyzExampleDigestFr"
      },
      {
        "id": "https://example.edu/templates/degree-hi.svg",
        "mediaType": "image/svg+xml",
        "contentLanguage": "hi",
        "digestMultibase": "zQmXyzExampleDigestHi"
      }
    ]
  }

Rendering software could then choose the most appropriate one based on the user’s preferred language or fallback logic.

[msporny]

I'm tagging some of the W3C Internationalization (i18n) folks on this thread since we're a few months away from requesting a horizontal review from them on the Verifiable Credentials Render Method specification (this repo has been adopted by the W3C VCWG, is in the process of being transferred to W3C, and we're getting ready to do an FPWD and then an immediate request for horizontal review). This is going to be one of the primary topics that we want their input on.

What do the i18n folks think about the pattern above, whose purpose is to signal that a resource identified using the id value has a specific content language. We are trying to perform visual renderings of a Verifiable Credential by using the JSON data and an SVG template as inputs, and an internationalized visual rendering as output.

/cc @aphillips @r12a @xfq @bert-github

[aphillips]

@msporny Thanks for this. When the normal W3C set of labels gets added to this repo, please add the i18n-tracker label to this issue. In the meantime, I'm adding this to I18N's agenda. An early horizontal review, such as you discuss, sounds like a good idea. We might also set up a joint call/meeting.

We have a WG Note that might have some useful information in it: Localizable Manifests.

You might find some useful concepts in this draft of an article about website locale negotiation (which is not at all the same thing as what you're doing, but has a number of similarities).

[msporny]

@aphillips wrote:

When the normal W3C set of labels gets added to this repo, please add the i18n-tracker label to this issue.

Done.

I expect that we'll be sending a horizontal review request out in December some time and would appreciate a joint call/meeting as there are some nuances here that I'm concerned might be missed. For example, I've reviewed both links you provided, which were very helpful (good alignment on a number of items we've been discussing for years). Those documents might have a more direct relevance than I was able to glean from a quick read through of both documents... but if I had to summarize what we're trying to do here, it is slightly different (maybe):

We are publishing a data file (JSON, YAML, etc.) that identifies a set of resources. Each resource is identified via a URL. This resource is going to be displayed to a human. We want to ensure that the resource selected is aligned with the language and locale preferences of the human. How do we best express the data to achieve that use case?