Translation Progress Badge

A small image that shows how much of your Locize project is translated. Put it in a README, in your documentation or on your website. It updates by itself when your translations change.

You build the badge from a URL. You need no dashboard step, and nothing has to be enabled.

What the badge shows

• The figure is the number of translated segments divided by the number of all segments, over all namespaces, rounded to two decimals (e.g. 49.48%).
• The reference language counts too. It is usually 100% translated, so a project or version figure is higher than the average of your target languages. For the figure of one target language, use a language badge.
• The figures come from the same translation statistics as the progress in the Locize dashboard.

How it works

1. Locize keeps a small JSON file with the progress figures of your project on the CDN, the badge data:
   • Standard CDN: https://api.lite.locize.app/badgedata/{projectId}
   • Pro CDN: https://api.locize.app/badgedata/{projectId}
2. Locize rewrites this file whenever translations are saved and whenever a version is published.
3. shields.io, a free badge service, draws the badge: its Dynamic JSON Badge reads one figure from the file and renders it as an SVG image.

The badge data looks like this:

{
  "versions": {
    "production": {
      "languages": {
        "en": { "name": "English", "nativeName": "English", "isReferenceLanguage": true, "translated": 1, "translatedPercentage": 100 },
        "de": { "name": "German", "nativeName": "Deutsch", "isReferenceLanguage": false, "translated": 0.9, "translatedPercentage": 90 }
      },
      "translated": 0.95,
      "translatedPercentage": 95
    }
  },
  "translated": 0.95,
  "translatedPercentage": 95
}

• translatedPercentage is the figure in percent, translated the same figure as a fraction from 0 to 1.
• A language code with a region (e.g. de-CH) also carries "region": "CH".
• The file is public and allows cross-origin requests, so you can also fetch it from your own code and show the figures any way you like.

Before you start

Nothing to enable:

• Every project has badge data as soon as it has translation statistics, i.e. after the first saved translation. No plan, add-on or setting is needed.
• Publishing is not required: saving translations already updates the badge data.
• The badge data stays public even when your translations are published as private downloads. It contains your version names, language codes and names, and the progress figures; no keys and no translations.

The badge URL

https://img.shields.io/badge/dynamic/json?url={badgeDataUrl}&query={query}&label=Locize&suffix=%25%20translated

• Write texts URL-encoded: %25 for %, %20 for a space, %3A for :.
• shields.io offers a few more parameters, e.g. a logo; see the Dynamic JSON Badge documentation.

Which figure (query):

Replace production and de with your version name and language code. Keep the brackets and quotes: they also work for names with dots or hyphens, such as v1.2 or de-CH.

Copy-ready snippets

Replace YOUR_PROJECT_ID with your project id. The snippets use the Standard CDN; on the Pro CDN, use api.locize.app instead of api.lite.locize.app.

Markdown (e.g. a README on GitHub or GitLab):

[![Translation progress](https://img.shields.io/badge/dynamic/json?url=https://api.lite.locize.app/badgedata/YOUR_PROJECT_ID&query=%24.translatedPercentage&label=Locize&suffix=%25%20translated&color=2096F3&style=plastic)](https://www.locize.com)

HTML:

<a href="https://www.locize.com">
  <img src="https://img.shields.io/badge/dynamic/json?url=https://api.lite.locize.app/badgedata/YOUR_PROJECT_ID&query=%24.translatedPercentage&label=Locize&suffix=%25%20translated&color=2096F3&style=plastic" alt="Translation progress">
</a>

• The link around the image is up to you: your Locize project, your contribution guide for translators, or the Locize website. The shields.io link parameter does not work in an <img> tag or in Markdown, so wrap the image in a link instead.
• color=2096F3 and style=plastic give the look of Locize; leave them out for the shields.io defaults.

Examples

Both examples use a public Locize demo project on the Pro CDN.

Version badge for the version production:

![Translation progress production](https://img.shields.io/badge/dynamic/json?url=https://api.locize.app/badgedata/3d0aa5aa-4660-4154-b6d9-907dbef10bb2&query=%24.versions%5B'production'%5D.translatedPercentage&label=Locize&prefix=production%3A%20&suffix=%25%20translated&color=2096F3&style=plastic)

Language badge for German (de) in the version production:

![Translation progress German](https://img.shields.io/badge/dynamic/json?url=https://api.locize.app/badgedata/3d0aa5aa-4660-4154-b6d9-907dbef10bb2&query=%24.versions%5B'production'%5D.languages%5B'de'%5D.translatedPercentage&label=Locize&prefix=de%3A%20&suffix=%25%20translated&color=2096F3&style=plastic)

For one badge per language, repeat the language badge with each language code.

Updates and caching

• Locize rewrites the badge data when translations are saved and when a version is published.
• The badge can lag behind the dashboard by up to about an hour: the CDN caches the badge data for up to one hour, and shields.io and GitHub cache the image as well.

Troubleshooting

Open the badge data URL in the browser to see which case applies.