A Crowdin CLI egy YAML konfigurációs fájlt használ, amely tartalmazza a kezelni kívánt források leírását: a Crowdin számára feltöltött fájlok aktuális adatait, valamint azokat a helyeket, ahol azok fordításai tárolásra kerülnek.
A Crowdin CLI használatához először hozza létre a saját YAML konfigurációját, majd futtassa az eszközt. A Crowdin CLI alapértelmezés szerint egy crowdin.yaml nevű konfigurációs fájlt keres (tehát nem kell megadnia a konfigurációs nevet, hacsak az nem különbözik crowdin.yaml-tól).
A konfigurációs fájl létrehozásához futtassa a következő parancsot:
$ crowdin initAz érvényes Crowdin CLI konfigurációs fájl a következő struktúrával rendelkezik, ezért kérjük, töltse ki az összes szükséges információt:
Egy tipikus YAML konfigurációs fájl az alábbihoz hasonló:
"project_id": "projectId" #open project settings and go to API section
"api_token": "personal-access-token" #open profile settings and go to API & SSO > New Token > create Token
"base_path": "/project-base-path"
"base_url": "https://crowdin.com"
"preserve_hierarchy": true
"files": [
{
"source": "/locale/en/folder1/[0-2].txt", #source files filter
"translation": "/locale/%two_letters_code%/folder1/%original_file_name%" #where translations are stored
},
{
"source": "/locale/en/folder2/[0-2].txt",
"translation": "/locale/%two_letters_code%/folder2/%original_file_name%"
}
]
A fenti konfigurációs fájl futtatása és a forrásfájlok feltöltése a Crowdinba:
$ crowdin upload sourcesFordítások letöltése Crowdinról és a megfelelő helyre tenni őket:
$ crowdin downloadAz API hitelesítő adatokat egy környezeti változóból is betöltheti, pl.:
"project_id_env": "CROWDIN_PROJECT_ID"
"api_token_env": "CROWDIN_PERSONAL_TOKEN"
"base_path_env": "CROWDIN_BASE_PATH"
"base_url_env": "CROWDIN_BASE_URL"
Ha kevert, akkor az api_token és a project_id prioritásai a következők:
"project_id_env": "CROWDIN_PROJECT_ID" # Low priority
"api_token_env": "CROWDIN_PERSONAL_TOKEN" # Low priority
"base_path_env": "CROWDIN_BASE_PATH" # Low priority
"base_url_env": "CROWDIN_BASE_PATH" # Low priority
"project_id": "projectId" # High priority
"api_token": "personal-access-token" # High priority
"base_path": "/project-base-path" # High priority
"base_url": "https://crowdin.com" # High priority
A crowdin.yaml fájl tartalmaz egy leírást a források kezeléséhez, illetve tartalmazza az API hitelesítő adatokat (project_id, api_token, base_path, base_url). Ez azt jelenti, hogy nem biztonságos a fájl tárolása az adattárban, mert az API kulcs így elérhető a többi felhasználó számára. A Crowdin CLI kétféle konfigurációs fájlt támogat:
Ha felhasználó-specifikus hitelesítő adatokkal kell parancsot futtatnia (például upload sources), akkor futtassa a következő parancsot:
$ crowdin upload sources --identity 'path-to-user-credentials-file'De ha a felhasználó-specifikus hitelesítő fájl a $HOME/.crowdin.yaml alatt található, akkor egyszerűen így is futtathatja:
$ crowdin upload sourcesA fent bemutatott minta-konfiguráció olyan forrás- és fordítási attribútumokat tartalmaz, amelyek szabványos helyettesítő karaktereket tartalmaznak (más néven globbing minták), hogy megkönnyítsék a több fájl kezelését.
Ezeket a mintákat használhatja:
* (csillag)
A fájl vagy a könyvtár nevében megjelenő karaktereket ábrázolja. Ha “*.json”-t ad meg, akkor minden olyan fájlt tartalmazni fog, mint a “messages.json”, az “about_us.json” és bármi, melynek kiterjesztése a “.json”.
** (dupla csillag)
Rekurzív módon megfelel bármely karakterláncnak (beleértve az alkönyvtárakat is). A **\ mind a forrás, mind a fordítási mintákban is használható. Ha a ** használatra kerül a fordítási mintában, akkor az mindig tartalmazni fog egy forrás alkönyvtárt egy bizonyos fájlhoz. Példaként a forráshoz használhatja ezt: ‘/en/**/*.po’ az összes *.po fájl Crowdinba való rekurzív feltöltéséhez. A fordítási minta: ‘/%two_letters_code%/**/%original_file_name%’ lesz.
? (kérdőjel)
Egyetlen karaktert helyettesít.
[set]
Egy adott karaktert helyettesít egy csomagból. Pontosan úgy viselkedik, mint a Regexp karakterkészletei, beleértve a beállított tagadást ([^a-z]).
\ (fordított perjel)
Védi a következő metakaraktert.
A Crowdin CLI lehetővé teszi a következő helyőrzők használatát, hogy a megfelelő változókat az eredményül kapott fájl nevére alkalmazza:
| Név | Leírás |
|---|---|
| %language% | Nyelv neve (pl. ukrán) |
| %two_letters_code% | ISO 639-1 nyelvkód (pl. uk) |
| %three_letters_code% | ISO 639-2/T nyelvkód (pl. ukr) |
| %locale% | Területi beállítások (pl. uk-UA) |
| %locale_with_underscore% | Területi beállítások (pl. uk_UA) |
| %original_file_name% | Eredeti fájlnév |
| %android_code% | Android területi azonosító, a "values-" könyvtárak elnevezésére használható |
| %osx_code% | OS X területi azonosító az ".lproj" könyvtárak elnevezésére használható |
| %original_path% | Használja a szülőmappa nevét a Crowdin projektben, hogy létrehozza a fájl elérési útját az eredményül kapott csomagban |
| %file_extension% | Eredeti fájlkiterjesztés |
| %file_name% | Fájl neve kiterjesztés nélkül |
A létrehozott archívumban lévő fájlok elérési útját is megadhatja úgy, hogy a minta elején egy perjelet (/) helyez el.
A translation beállítása a következőképp kell kinézzen: “/locale/%two_letters_code%/LC_MESSAGES/%original_file_name%”.
A helyi gépen található fájlok és könyvtárak struktúrája:
- base_path | |-- folder | | | |-- 1.xml | |-- 1.txt | |-- 123.txt | |-- 123_test.txt | |-- a.txt | |-- a1.txt | |-- crowdin?test.txt | |-- crowdin_test.txt | |-- 1.xml |-- 1.txt |-- 123.txt |-- 123_test.txt |-- a.txt |-- a1.txt |-- crowdin?test.txt |-- crowdin_test.txt |-- 3.txt
#........your project configuration........
"files": [
{
"source": "/**/?[0-9].txt", #upload a1.txt, folder/a1.txt
"translation": "/**/%two_letters_code%_%original_file_name%"
},
{
"source": "/**/*\\?*.txt", #upload crowdin?test.txt, folder/crowdin?test.txt
"translation": "/**/%two_letters_code%_%original_file_name%"
},
{
"source": "/**/[^0-2].txt", #upload 3.txt, folder/3.txt, a.txt, folder/a.txt (ignore 1.txt, folder/1.txt)
"translation": "/**/%two_letters_code%_%original_file_name%"
}
]
#........your project configuration........
"files": [
{
"source": "/**/*.*", #upload all files that the base_path contains
"translation": "/**/%two_letters_code%_%original_file_name%",
"ignore": [
"/**/%two_letters_code%_%original_file_name%", #ignore the translated files
"/**/?.txt", #ignore 1.txt, a.txt, folder/1.txt, folder/a.txt
"/**/[0-9].txt", #ignore 1.txt, folder/1.txt
"/**/*\\?*.txt", #ignore crowdin?test.txt, folder/crowdin?test.txt
"/**/[0-9][0-9][0-9].txt", #ignore 123.txt , folder/123.txt
"/**/[0-9]*_*.txt" #ignore 123_test.txt, folder/123_test.txt
]
}
]
Gyakran a szoftverprojektek a honosítási könyvtárakhoz egyéni neveket tartalmaznak. A Crowdin Enterprise lehetővé teszi a saját nyelveinek hozzárendelését, hogy felismerhetőek legyenek a projektjeiben.
Tegyük fel, hogy a nyelvi könyvtárak elnevezése “en”, “uk”, “fr”, “de”. Közülük mindegyik megjeleníthető a %two_letters_code% helyőrzővel. Ezen felül van egy “zh_CH” nevű könyvtára. Ahhoz, hogy ez a Crowdinnal a projektje módosítása nélkül működjön, beállíthatja a Nyelv hozzárendelését. A nyelvkódokat felül is írhatja, például az %android_code%, %locale%, stb. helyőrzőkkel.
A Nyelv hozzárendelését a felhasználói felületen (UI) állíthatja be:
Ha át kell neveznie a fordítás fájlokat az exportálás után, könnyen elvégezheti ezt a translation_replace paraméter segítségével.
Például, ha a fájl neve “en_strings.po”, átnevezhető “strings.po”-ra. Ehhez a konfigurációs fájlhoz (crowdin.yaml) adjon hozzá egy új paramétert (azonos szinten a fordítási paraméterrel):
"files": [
{
"source": "/locale/**/en_*.po",
"translation": "/locale/**/%two_letters_code%_%original_file_name%",
"translation_replace": {
"en_": ""
}
}
]
Ebben az esetben az “_en” egyszerűen törlődik a fájlnévből.
Időről időre olyan fájlok és könyvtárak vannak, amelyeket nem kell a Crowdinban lefordítani. Ilyen esetekben a helyi fájlonkénti szabályok hozzáadhatók a projekt konfigurációs fájljához.
"files": [
{
"source": "/**/*.properties",
"translation": "/**/%file_name%_%two_letters_code%.%file_extension%",
"ignore": [
"/test/file.properties",
"/example.properties"
]
},
{
"source": "/locale/en/**/*.po",
"translation": "/locale/%two_letters_code%/**/%original_file_name%",
"ignore": [
"/locale/en/templates",
"/locale/en/workflow"
]
}
]
Ha egy CSV fájl az összes célnyelv fordítását tartalmazza, a sémában meg kell adnia a megfelelő nyelvkódokat.
CSV fájl példa:
identifier,source_phrase,context,Ukrainian,Russian,French ident1,Source 1,Context 1,,, ident2,Source 2,Context 2,,, ident3,Source 3,Context 3,,,Konfigurációs fájl példa:
"files": [
{
"source": "multicolumn.csv",
"translation": "multicolumn.csv",
"first_line_contains_header": true,
"scheme": "identifier,source_phrase,context,uk,ru,fr"
}
]
Ha a CSV fájl olyan oszlopokat tartalmaz, melyeket az importálásnál ki kell hagyni, használja a none értéket az ilyen oszlopokra a sémában, például:
"scheme" : "identifier,source_phrase,context,uk,none,ru,none,fr"
"preserve_hierarchy": true
Példa a preserve_hierarchy funkció használatára a fájl konfigurációjában:
"project_id": "projectId" #open project settings and go to API section
"api_token": "personal-access-token" #open profile settings and go to API & SSO > New Token > create Token
"base_path": "/project-base-path"
"base_url": "https://crowdin.com"
"preserve_hierarchy": true
"files": [
{
"source": "/locale/en/**/*.po",
"translation": "/locale/%two_letters_code%/**/%original_file_name%"
}
]
Alapértelmezés szerint az olyan könyvtárak, amelyek nem tartalmaznak fordítási fájlokat, nem hozhatók létre a Crowdinban. Például:
- locale | |-- en | |-- foo.po |-- bar.po
A projektfájlok alapértelmezés szerint a Crowdinban a következők szerint jelennek meg:
- foo.po
- bar.po
A preserve_hierarchy funkció használatával a Crowdinban lévő fájlstruktúra a következő lesz:
- en | |-- foo.po |-- bar.po
Ez a funkció 2 opcionális paraméter támogatását biztosítja a yaml fájlban: dest és type. Ez jellemzően néhány olyan projekt esetében használatos, ahol a feltöltött névnek másnak kell lennie, így a Crowdin képes felismerni a típust. A dest paraméter lehetővé teszi, hogy megadja a fájl nevét a Crowdinban.
dest paraméter csak szimpla fájlokon működik, és ha használja, akkor a konfigurációs fájlnak tartalmaznia kell a preserve_hierarchy paramétert a true értékkel.Konfigurációs fájl példa mindkét paraméterrel:
"project_id": "projectId" #open project settings and go to API section
"api_token": "personal-access-token" #open profile settings and go to API & SSO > New Token > create Token
"base_path": "/project-base-path"
"base_url": "https://crowdin.com"
"preserve_hierarchy": true
"files": [
{
"source": "/conf/messages",
"dest": "/messages.properties",
"translation": "/conf/messages.%two_letters_code%",
"type": "properties"
},
{
"source": "/app/strings.xml",
"dest": "/strings.xml",
"translation": "/res/values-%android_code%/%original_file_name%",
"type": "properties"
}
]
Az update_option paraméter opcionális. Ha nincs beállítva, a megváltoztatott karakterláncok fordításai a fájlfrissítés után elveszhetnek. Hasznos az elgépelések javításaihoz és a kisebb forrás-karakterlánc változásokhoz.
Az értéktől függően, az update_option a fordítások megőrzésére és a módosított karakterláncok jóváhagyásainak megőrzésére/eltávolítására használható a fájlfrissítés során.
Az értékek:
Konfigurációs fájl példa update_option paraméterrel:
"project_id": "projectId" #open project settings and go to API section
"api_token": "personal-access-token" #open profile settings and go to API & SSO > New Token > create Token
"base_path": "/project-base-path"
"base_url": "https://crowdin.com"
"files": [
{
"source": "/*.csv",
"translation": "/%three_letters_code%/%file_name%.csv",
"first_line_contains_header": true,
"scheme": "identifier,source_phrase,translation,context",
"update_option": "update_as_unapproved"
},
{
"source": "/**/*.xlsx",
"translation": "/%three_letters_code%/folder/%file_name%.xlsx",
"update_option": "update_without_changes"
}
]
Az upload translations parancs feltölti a meglévő fordításokat a Crowdinba. Ha nincs megadva opció, a feltöltött fordítások akkor sem kerülnek importálásra, ha azok duplikáltak, vagy egyenlőek a forrás-karakterláncokkal, és nem lesznek jóváhagyva.
Az értékek:
| translate_content opcionális | bool | Meghatározza, hogy a jelölőkön belüli szövegeket le kell e fordítani. Elfogadható értékek: 0 vagy 1. Alapértelmezett értéke 1. |
| translate_attributes opcionális | bool | Meghatározza, hogy le kell e fordítani a jelölő attribútumokat. Elfogadható értékek: 0 vagy 1. Alapértelmezett értéke 1. |
| content_segmentation opcionális | bool | Meghatározza, hogy a hosszú szövegeket kisebb szövegekre szétdarabolja e. Elfogadható értékek: 0 vagy 1. Alapértelmezett értéke 1. Fontos! Ez az opció letiltja az XML fájlok meglévő fordítások feltöltésének lehetőségét, ha engedélyezve van. |
| translatable_elements opcionális | array | Ez egy karakterláncok tömb, ahol minden elem az XPaths a DOM-hoz elem, amelyet importálni kell. Minta útvonal: /path/to/node vagy /path/to/attribute[@attr] Figyelem! Ha be van állítva, a translate_content és a translate_attributes paramétereket nem veszi figyelembe az importálás során. |
Konfigurációs fájl példa további paraméterekkel:
"project_id": "projectId" #open project settings and go to API section
"api_token": "personal-access-token" #open profile settings and go to API & SSO > New Token > create Token
"base_path": "/project-base-path"
"base_url": "https://crowdin.com"
"files": [
{
"source": "/app/sample1.xml",
"translation": "/app/%locale%/%original_file_name%",
"translate_attributes": 1,
"translate_content": 0
},
{
"source": "/app/sample2.xml",
"translation": "/app/%locale%/%original_file_name%",
"translatable_elements": [
"/content/text", # translatable texts are stored in 'text' nodes of parent node 'content'
"/content/text[@value]" # translatable texts are stored in 'value' attribute of 'text' nodes
]
}
]
Meghatározza, hogy egy adott aposztrófot egy másik aposztróffal, vagy fordított perjellel kell védeni (escape) az exportált fordításokban. Az escape_quotes-t fájlonkénti opcióként adhatja hozzá. Elfogadható értékek: 0, 1, 2, 3. Alapértelmezett értéke 3.
Az értékek:
Speciális karakterek védése
Meghatározza, hogy a speciális karaktereket (=, :, ! és #) az exportált fordításokban védeni kell-e egy fordított perjellel. Az escape_special_characters paramétert fájlonként adhatja hozzá.
Elfogadható értékek: 0, 1. Alapértelmezett értéke 1.
Példa a konfigurációs fájlra:
"project_id": "projectId" #open project settings and go to API section
"api_token": "personal-access-token" #open profile settings and go to API & SSO > New Token > create Token
"base_path": "/project-base-path"
"base_url": "https://crowdin.com"
"files": [
{
"source": "/en/strings.properties",
"translation": "/%two_letters_code%/%original_file_name%",
"escape_quotes": 1,
"translate_content": 0,
"escape_special_characters": 0
}
]
"project_id": "projectId" #open project settings and go to API section
"api_token": "personal-access-token" #open profile settings and go to API & SSO > New Token > create Token
"base_path": "/project-base-path"
"base_url": "https://crowdin.com"
"files": [
{
"source": "/*.csv",
"translation": "/%two_letters_code%/%original_file_name%",
# Specifies whether first line should be imported or it contains columns headers
"first_line_contains_header": true,
# used only when uploading CSV file to define data columns mapping
"scheme": "identifier,source_phrase,translation,context,max_length"
}
]
"project_id": "projectId" #open project settings and go to API section
"api_token": "personal-access-token" #open profile settings and go to API & SSO > New Token > create Token
"base_path": "/project-base-path"
"base_url": "https://crowdin.com"
"files" : [
{
"source" : "/locale/en/**/*.po",
"translation" : "/locale/%two_letters_code%/LC_MESSAGES/%original_file_name%",
"languages_mapping" : {
"two_letters_code" : {
"zh-CN" : "zh_CH",
"fr-QC": "fr"
}
}
}
]
"project_id": "projectId" #open project settings and go to API section
"api_token": "personal-access-token" #open profile settings and go to API & SSO > New Token > create Token
"base_path": "/project-base-path"
"base_url": "https://crowdin.com"
"files" : [
{
"source" : "/res/values/*.xml",
"translation" : "/res/values-%android_code%/%original_file_name%",
"languages_mapping" : {
"android_code" : {
"de" : "de",
"ru" : "ru"
}
}
}
]
A VCS integrációk ugyanazt a konfigurációs fájlt igénylik, mint a CLI eszköz, azaz ugyanazt a struktúrát támogatja. Az egyetlen különbség az, hogy a projekthitelesítő adatokat biztonsági okokból nem szabad a fájl fejlécében tárolni. Emellett két további paraméter is használható.
Minden alkalommal, amikor fordítások kerülnek beküldésre a következő alapértelmezett üzenet jelenik meg: “Új fordítások {fileName} ({languageName})”. Használhatja a commit_message paramétert is a Git jelölők hozzáadásához (pl. építések átugrásához).
Minta:
"base_path": "/project-base-path"
"commit_message": "[ci skip]"
"files": [
{
"source" : "/resources/en/*.json",
"translation" : "/resources/%two_letters_code%/%original_file_name%"
}
]
Az alapértelmezett beküldési üzenet lecseréléséhez használja az append_commit_message paramétert a false értékkel. Két opcionális helyőrzőt is hozzáadhat: %original_file_name% és %language% a megfelelő fájlnév és a megfelelő nyelvi változók használatához.
Minta:
"commit_message": "Fix: New translations %original_file_name% from Crowdin"
"append_commit_message": false
"files": [
{
"source" : "/resources/en/*.json",
"translation" : "/resources/%two_letters_code%/%original_file_name%"
}
]
Alapértelmezés szerint az összes nyelv exportálásra kerül. Ha csak bizonyos nyelveket kell exportálnia, akkor az export_languages paraméterrel adja meg azokat.
Minta:
"base_path": "/project-base-path"
"export_languages": [
"ru",
"uk",
"ja"
]
"files": [
{
"source" : "/resources/en/*.json",
"translation" : "/resources/%two_letters_code%/%original_file_name%"
}
]
Előfordulhatnak olyan esetek, amikor a VCS integrációt és a CLI-t kell használni egy projekthez. Az ilyen helyzetben legtöbbször két különálló konfigurációs fájlra van szüksége, az egyik a VCS integrációhoz, a másik pedig a CLI-hez. Ugyanakkor lehetséges egyetlen konfigurációs fájl használata a két esethez.
Mivel a VCS integrációhoz tartozó konfigurációs fájl nem tartalmazza a CLI-hez szükséges projekt_id és api_token hitelesítő adatokat, közvetlenül átadhatja azokat a parancsban a következő paraméterekkel: -i/--project-id, -T/--token. Alternatív megoldásként erre a célra használhatkörnyezeti változókat is.
Ennek eredményeként a fordítások CLI-n keresztüli letöltésére szolgáló parancs a következőképpen néz ki:
$ crowdin download -i {your-project-id} -T {your-token}Segítségre van szüksége a Crowdin CLI használatával, vagy kérdése van? Lépjen kapcsolatba az ügyfélszolgálattal.