Badge request: Crowdin

[Andre601]

:clipboard: Description It would be a nice addition, to have Crowdin's "Localized" badge (https://badges.crowdin.net/:project/localized.svg) with the customisation options of Shields.io

:link: Data There are two APIs available. The current v1 AP and the v2 API (Beta)

Docs v1: https://support.crowdin.com/api/api-integration-setup/ Docs v2: https://support.crowdin.com/api/v2/#section/Introduction

v1 requires an API key (Generated with the project) and v2 a PAT (Personal Access Token). This is not guaranteed to be like that and I could be wrong here.

:microphone: Motivation Crowdin already offers a badge to display (See first link) but this badge is only limited to the overall translation of all languages and can't be customised in design nor f.e. to have it cover a specific language only.

[calebcartwright]

Thanks for the request @Andre601!

Could you enumerate the specific badge(s) you'd like to see from this service?

The scope of badges will determine whether we can/must use the API vs. SVG scraping approaches.

If we'd need to use the API then also worth noting that it seems they have some rate limiting (both v1 and v2), though I'm not entirely sure how they are defining "simultaneous"

https://support.crowdin.com/api/v2/#section/Introduction/Rate-Limits

The number of simultaneous API requests per account is 20 requests

IIUC, it looks like the v1 authorization flow is a project-specific API key which is a pattern Shields avoids unless absolutely necessary and the key/token can be scoped to read-only. It's not clear to me what the authorization scope would be for a PAT with the v2 API. Ideally we'd be able to create a Shields account and use a Shields-owned token for all badges, but that'll depend on auth of course.

[Andre601]

Some ideas for badges that I had:

• The current progress of all translations (Same as https://badge.crowdin.com/:project/localized.svg but with customisation options (i.e. Style) from Shields.io)
• The current progress of a specific translation
• Amount of members in the project
• The current progress of approved strings and words (one per each maybe?)
• Amount of Strings or words in the project.

[chris48s]

the key/token can be scoped to read-only. It's not clear to me what the authorization scope would be for a PAT with the v2 API

:+1: it would need to be possible for the user to call the badges without exposing a token that allows write access to their project or access to any sensitive info. I think if every user supplies their own account-scoped token as a GET param, I'm not too worried about the rate limit as one really popular project can't break everyone else's badge - only their own.

[calebcartwright]

I think if every user supplies their own account-scoped token as a GET param, I'm not too worried about the rate limit as one really popular project can't break everyone else's badge - only their own.

That's a good point @chris48s

[SethFalco]

Some issues:

• There is no way to limit an API key/token to read-only.
• Most of the information (even for public projects) can't be accessed unless you have the Manager role for the project.

The only endpoint publicly accessible that I'd think is relevant for shields.io with an API key is:

• Get Project Progress (total words, total translated, total approved, translated percentile, and approved percentile, per language)
  https://api.crowdin.com/api/v2/projects/:projectId/languages/progress?limit=500 (example project ID: 3579)

For most projects, that request can be done with one call, but it's technically paginated per 500 languages. (Should be implemented to handle this scenario anyway, but for most usage it'll very rarely do more than 1 request.)

It also accepts the languageIds query parameter to limit based on language, it accepts a comma separated list of language codes. (Useful for a :crowdin/progress/:projectId/:language badge)

All other endpoints, for example seeing the number of managers, translators, files, etc. aren't accessible, even though it's publicly available on the website anyway.

To cover other data points, some solutions could be:

• Web scrapping (I assume it's adverse, but just had to point it out, even if it's prone to breaking.)
• Making it for self-hosted instances only, not available on the public instance.
• Users could invite the Crowdin user that owns the token for the Shields.io instance as a Manager on the project. (But if the server gets compromised, that grants write access to other parts of the project.)

Overall, I'm guessing project and project/language progress will be the only badges that will be made for Crowdin. Usage would be with an API key managed by the administrator of a shields.io instance.

Just wanted to document my findings here.

[chris48s]

Thanks for doing some research on this and investigating the available options :+1: Most of the possible approaches here require something that we've at some point explicitly documented that we don't do (mostly as a result of learning from our mistakes).

From https://github.com/badges/shields/blob/7d452472defa0e0bd71d6443393e522e8457f856/CONTRIBUTING.md#badge-guidelines

Badges should not obtain data by scraping web pages - these are likely to break frequently. Whereas API publishers are incentivised to maintain a stable platform for their users, authors of web pages have no such incentive.

Badges may require users to specify a token in the badge URL as long it is scoped only to fetching information and doesn't expose any sensitive information. Generating a token with the correct scope must be clearly documented.

..and from https://github.com/badges/shields/blob/7d452472defa0e0bd71d6443393e522e8457f856/doc/releases.md#important-information

We do not accept new badges that cannot be utilized with Shields.io (e.g. those that would always require user-specific authorization)

I think unless there is a change to the upstream service (e.g: they enable read-only tokens or anonymous access) there isn't a way forwards to deliver this on shields.io in a sensible way.

[tolot27]

It looks like this is already integrated but I could not access it. See https://store.crowdin.com/products/bds.

[ReenigneArcher]

It looks like this is already integrated but I could not access it. See https://store.crowdin.com/products/bds.

These are the steps I took to enable it.

• Login to CrowdIn
• At the top, click Resources/Marketplace
• Filter "bds"
• Select it, and then click "Install"
• Go to your project
• Click "Tools"
• Select the bds resource
• Click "Enable for this project"

One issue is there doesn't seem to be a total localized like the badge provided by Crowdin; however you can have a single badge that shows all the percentages. This would be nice to have, as I don't plan on displaying a badge for each and every language.

![Crowdin](https://img.shields.io/badge/dynamic/json?color=blue&label=localized&style=for-the-badge&query=%24.progress..data.translationProgress&url=https%3A%2F%2Fbadges.awesome-crowdin.com%2Fstats-15178612-503340.json&logo=crowdin)

There's also a language chart, which could be nice in some situations.

[andrii-bodnar]

Hey everyone,

There is a Badges & Status Images app that allows generating customizable badges, charts, and additional graphics for each language in your Crowdin Project.

Under the hood, it's using shields.io, but it would be great to add these badges as a native 🙂