Crowdin Query Language (CroQL) is a tool for Crowdin and Crowdin Enterprise API that allows you to retrieve needed localization resources based on specific conditions. Using CroQL, you can filter source strings and their translations for a specific target language.
You can use CroQL with the following API methods:
Main CroQL operators are listed below. Use and combine them to set specific conditions for retrieving the needed content from Crowdin. To form your CroQL query, you can use the elements from the tables below.
The arithmetic operators are used to perform mathematic operations with any numeric data types.
Name | Symbol | Example |
---|---|---|
Addition | + | 1 + 9 |
Subtraction | - | 11 - 1 |
Division | / | 20 / 2 |
Multiplication | * | 2 * 5 |
Negation | - | -10 |
The comparison operators are used to compare values and return true
or false
.
Name | Symbol | Aliases | Example |
---|---|---|---|
Between | {{expression}} between {{expression}} and {{expression}} | 5 between 1 and 10 | |
Equal | = | 10 = 10 | |
Not equal | != | ≠ | 1 != 10; 1 ≠ 10 |
Greater | > | 10 > 1 | |
Greater or equal | >= | ≥ | 10 >= 1; 10 ≥ 1 |
Less | < | 1 < 10 | |
Less or equal | <= | ≤ | 1 <= 10; 1 ≤ 10; |
Contains | {{string}} contains {{string}} | "Hello World" contains "Hello"; "Hello World" contains text; text contains "Hello World"; context contains text; |
The logical operators are used to combine multiple boolean expressions or values and provide a single boolean output.
Name | Symbol | Example |
---|---|---|
And | and | 1 < 10 and 10 > 1 |
Or | or | 1 < 10 or 10 > 1 |
Xor | xor | 1 < 10 xor 10 > 1 |
Not | not | not 1 < 10 |
The filtration operators are used to filter the objects based on the specified condition.
Name | Symbol | Example |
---|---|---|
Filter | {{collection}} where {{predicate}} | translations where (count of votes > 0) |
Match | {{object}} with {{predicate}} | user with (login = "crowdin") |
The ternary operator is used to check a condition specified in the first value, and if it’s true
it returns the second value, but if it’s false
it returns the third value.
Name | Symbol | Example |
---|---|---|
Ternary | If {{condition}} then {{expression}} else {{expression}} | If 1 < 10 then "less" else "greater" |
The fetch operators are used for retrieving data from the objects.
Name | Symbol | Example |
---|---|---|
Mention | @user:{{string}}; @language:{{string}} | @user:"crowdin"; @language:"en" |
Member | {{member}} of {{object}} | count of translations |
Identifier | {{identifier}} | text; identifier |
The scalar operators are used to declare values for further processing.
Name | Symbol | Example |
---|---|---|
Integer | {{integer}} | 10 |
Float | {{float}} | 10.01 |
String | {{string}} | “crowdin" |
Datetime | {{datetime}} | 'today'; '2021-03-16 00:00:00' |
The group operator is used to determine the execution order of operators.
Name | Symbol | Example |
---|---|---|
Group | ( ) | 1 < 10 and (20 > 10 or 10 > 5) |
To retrieve a list of strings that have no Ukrainian translations with approvals or votes, your query might look like this:
count of translations where ( language = @language:"uk" and ( count of approvals > 0 or count of votes > 0 ) ) = 0
Use your query in the following endpoint in Crowdin:
In Crowdin Enterprise:
{projectId} | Type: Description: Numeric identifier of your Crowdin project. |
{croql} | Type: Description: CroQL expression. |
To retrieve a list of strings that have only one translation, your query might look like this:
count of translations = 1
Use your query in the following endpoint in Crowdin:
In Crowdin Enterprise:
{projectId} | Type: Description: Numeric identifier of your Crowdin project. |
{croql} | Type: Description: CroQL expression. |
To retrieve a list of strings that have translations from only one specific user, your query might look like this:
count of translations > 0 and count of translations = count of translations where (user = @user:"crowdin")
Use your query in the following endpoint in Crowdin:
In Crowdin Enterprise:
{projectId} | Type: Description: Numeric identifier of your Crowdin project. |
{croql} | Type: Description: CroQL expression. |
To retrieve a list of strings that have at least one translation not from specific users, your query might look like this:
count of translations where (user != @user:"crowdin") > 0
Use your query in the following endpoint in Crowdin:
In Crowdin Enterprise:
{projectId} | Type: Description: Numeric identifier of your Crowdin project. |
{croql} | Type: Description: CroQL expression. |
To retrieve a list of strings that have all translations not from specific users, your query might look like this:
count of translations > 0 and count of translations = count of translations where (user != @user:"crowdin")
Use your query in the following endpoint in Crowdin:
In Crowdin Enterprise:
{projectId} | Type: Description: Numeric identifier of your Crowdin project. |
{croql} | Type: Description: CroQL expression. |
To retrieve translations made by the user with a crowdin
username or ones with ≥ 100 upvotes, your query might look like this:
user = @user:"crowdin" or count of votes where ( is up ) >= 100
Use your query in the following endpoint in Crowdin:
In Crowdin Enterprise:
{projectId} | Type: Description: Numeric identifier of your Crowdin project. |
{croql} | Type: Description: CroQL expression. |
To retrieve a list of strings filtered by identifier and numeric id of a file in your Crowdin project, your query might look like this:
identifier = "key" and id of file = 777
Use your query in the following endpoint in Crowdin:
In Crowdin Enterprise:
{projectId} | Type: Description: Numeric identifier of your Crowdin project. |
{croql} | Type: Description: CroQL expression. |
To retrieve a list of strings that have unresolved issues filtered by numeric id of a file in your Crowdin project, your query might look like this:
id of file = 777 and count of comments where (has unresolved issue) > 0
Use your query in the following endpoint in Crowdin:
In Crowdin Enterprise:
{projectId} | Type: Description: Numeric identifier of your Crowdin project. |
{croql} | Type: Description: CroQL expression. |
To retrieve a list of hidden strings that are not duplicates and have one or more translations, your query might look like this:
is hidden and not is duplicate and count of translations > 0
Use your query in the following endpoint in Crowdin:
In Crowdin Enterprise:
{projectId} | Type: Description: Numeric identifier of your Crowdin project. |
{croql} | Type: Description: CroQL expression. |
CroQL can be used in the following contexts: the source string context and translation context. Use the following examples as a foundation when forming your CroQL queries.
{
"type is plain": true,
"type is plural": false,
"type is icu": false,
"type is asset": false,
"text": "Quick Start",
"identifier": "quick_start",
"context": "quick_start",
"max length": 0,
"is visible": true,
"is hidden": false,
"is duplicate": false,
"file": {
"id": 32,
"name": "sample.csv",
"title": "Sample",
"type": "csv",
"context": "Some useful context information"
},
"comments": [
{
"has issue": false,
"has unresolved issue": false
}
],
"screenshots": [],
"translations": [
{
"text": "Швидкий старт",
"plural form": "none",
"is pre translated": true,
"provider": "tm",
"language": 52,
"user": 1,
"votes": [
{
"is up": true,
"is down": false,
"user": 2,
"added": "2021-04-09 13:44:14"
}
],
"approvals": [
{
"user": 2,
"added": "2021-04-09 13:44:14"
}
],
"updated": "2021-04-09 10:23:17"
}
],
"added": "2021-04-08 12:33:27",
"updated": "2021-04-08 12:33:27"
}
type is plain | Type: Description: The source string with plain text. |
type is plural | Type: Description: The source string with plural forms. |
type is icu | Type: Description: The source string with ICU. |
type is asset | Type: Description: The source string is an asset. |
text | Type: Description: The source string text. |
identifier | Type: Description: The source string identifier (key). |
context | Type: Description: The source string context. |
max length | Type: Description: The source string max.length. |
is visible | Type: Description: The source string is visible. |
is hidden | Type: Description: The source string is hidden. |
is duplicate | Type: Description: The source string is duplicate. |
file | Type: Description: The source string file. |
comments | Type: Description: The source string comments. |
has issue | Type: Description: The source string has an issue. |
has unresolved issue | Type: Description: The source string has an unresolved issue. |
screenshots | Type: Description: The source string screenshots. |
translations | Type: Description: Translations of the source string. |
text | Type: Description: Translation text. |
plural form | Type: Description: Translation plural form. |
is pre translated | Type: Description: Translation added via pre-translation. |
provider | Type: Allowed values: Description: Translation provided via translation memory or machine translation engine. |
language | Type: Description: Numeral identifier of the target language. |
user | Type: Description: Numeral identifier of the user who added a translation. |
votes | Type: Description: Array of the votes added to the translation. |
is up | Type: Description: Upvote. |
is down | Type: Description: Downvote. |
user | Type: Description: Numeral identifier of the user who added a vote for translation. |
added | Type: Description: Date when a vote for translation was added. |
approvals | Type: Description: Array of the added translation approvals. |
user | Type: Description: Numeral identifier of the user who approved a translation. |
added | Type: Description: Date when a translation approval was added. |
updated | Type: Description: Date when a translation was updated. |
added | Type: Description: Date when a source string was added. |
updated | Type: Description: Date when a source string was updated. |
{
"text": "Швидкий старт",
"plural form": "none",
"is pre translated": true,
"provider": "tm",
"user": 1,
"votes": [
{
"is up": true,
"is down": false,
"user": 2,
"added": "2021-04-09 13:44:14"
}
],
"approvals": [
{
"user": 2,
"added": "2021-04-09 13:44:14"
}
],
"updated": "2021-04-09 10:23:17"
}
text | Type: Description: Translation text. |
plural form | Type: Description: Translation plural form. |
is pre translated | Type: Description: Translation added via pre-translation. |
provider | Type: Allowed values: Description: Translation provided via translation memory or machine translation engine. |
user | Type: Description: Numeral identifier of the user who added a translation. |
votes | Type: Description: Array of the votes added to the translation. |
is up | Type: Description: Upvote. |
is down | Type: Description: Downvote. |
user | Type: Description: Numeral identifier of the user who added a vote for translation. |
added | Type: Description: Date when a vote for translation was added. |
approvals | Type: Description: Array of the added translation approvals. |
user | Type: Description: Numeral identifier of the user who approved a translation. |
added | Type: Description: Date when a translation approval was added. |
updated | Type: Description: Date when a translation was updated. |