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 generateAz é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:
Nézze meg az API integráció beállítása cikket, hogy megtanulja, hol találja a projekt hitelesítő adatait.
Egy tipikus YAML konfigurációs fájl az alábbihoz hasonló:
"project_identifier": "your-project-identifier"
"api_key": "54e01e81--your-api-key--f6a2724a" #a projekt beállítások oldalon találja meg
"base_path": "/home/office/source-code"
"files": [
{
"source" : "/resources/en/*.json", #source files filter
"translation" : "/resources/%two_letters_code%/%original_file_name%" #ahol a fordításokat tárolja
}
]Figyelem: A Windows rendszeren, ha Windows-stílusú könyvtár elválasztót használ, meg kell duplázni a YAML szintaxis szerint:
{
"source" : "\\resources\\en\\*.json",
"translation" : "\\resources\\%two_letters_code%\\%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.:
"api_key_env": CROWDIN_API_KEY
"project_identifier_env": CROWDIN_PROJECT_ID
"base_path_env": CROWDIN_BASE_PATHHa kevert, az api_key és a project_identifier elsőbbséget élvez:
"api_key_env": CROWDIN_API_KEY # alacsony prioritású
"project_identifier_env": CROWDIN_PROJECT # alacsony prioritású
"base_path_env": CROWDIN_BASE_PATH # alacsony prioritású
"api_key": "xxx" # magas prioritású
"project_identifier": "yyy" # magas prioritású
"base_path": "zzz" # magas prioritásúA crowdin.yaml fájl tartalmazza a kezelendő források leírását és az API hitelesítő adatokat (api_key, project_identifier, base_path). 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: + a projekt könyvtárában található leírást a források kezeléséhez + API hitelesítő adatok, amely valószínűleg a $HOME/.crowdin.yaml helyen van
Megjegyzés: A .crowdin.yaml konfigurációs fájl API hitelesítési adatai nagyobb prioritást élveznek, mint a projekt könyvtárában lévő hitelesítési adatok (crowdin.yaml).
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 **-t használja 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 CLI lehetővé teszi, hogy a saját nyelveit hozzárendelje a Crowdin számára felismerhető módon.
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. Annak érdekében, hogy a Crowdin CLI-vel dolgozhasson a projekt módosításai nélkül, hozzáadhat egy languages_mapping szakaszt a fájlkészlethez.
Minta konfiguráció:
#........your project configuration........
"files" : [
{
"source" : "/locale/en/**/*.po",
"translation" : "/locale/%two_letters_code%/**/%original_file_name%",
"languages_mapping" : {
"two_letters_code" : {
"ru" : "ros",
"uk" : "ukr"
}
}
}
]A hozzárendelési formátum a következő: “crowdin_nyelvkod” : “kod_amit_hasznal”. Nézze meg a Crowdin nyelvkódok teljes listáját, amelyeket felhasználhat a hozzárendeléshez.
A nyelvkódokat felül is írhatja, például az %android_code%, %locale% stb. helyőrzőkkel.
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 “strings_en.xml”, átnevezhető “strings.xml”-re. Ehhez a konfigurációs fájlhoz (crowdin.yaml) adjon hozzá egy új paramétert (azonos szinten a fordítási paraméterrel):
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"
}
]"preserve_hierarchy": truePélda a preserve_hierarchy funkció használatára a fájl konfigurációjában:
"project_identifier": "test"
"api_key": "KeepTheAPIkeySecret"
"base_url": "https://api.crowdin.com"
"base_path": "/path/to/your/project"
"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 egyetlen fájlhoz használhatóKonfigurációs fájl példa mindkét paraméterrel:
"project_identifier": "your-project-identifier"
"api_key": "54e01e81--your-api-key--f6a2724a" #can be found in your project settings page
"base_path": "/home/office/source-code"
"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%"
}
]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: * update_as_unapproved - a módosított karakterláncok fordításainak megőrzése és azok jóváhagyásainak megszüntetése, ha léteznek * update_without_changes - a módosított karakterláncok fordításainak és jóváhagyásainak megőrzése
Konfigurációs fájl példa update_option paraméterrel:
"project_identifier": "your-project-identifier"
"api_key": "54e01e81--your-api-key--f6a2724a" #can be found in your project settings page
"base_path": "/home/office/source-code"
"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ék 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ék 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_identifier": "your-project-identifier"
"api_key": "54e01e81--your-api-key--f6a2724a" #can be found in your project settings page
"base_path": "/home/office/source-code"
"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_quote-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á.
Az elfogadható értékek: 0, 1. Alapértelmezett érték 0.
Példa a konfigurációs fájlra:
"project_identifier": "your-project-identifier"
"api_key”: "54e01e81--your-api-key--f6a2724a" #can be found in your project settings page
"base_path”: "/home/office/source-code"
"files" : [
{
"source" : "/en/strings.properties",
"translation" : "/%two_letters_code%/%original_file_name%",
"escape_quotes" : 1,
"escape_special_characters: 0"
}
]"project_identifier": "test"
"api_key": "KeepTheAPIkeySecret"
"base_url": "https://api.crowdin.com"
"base_path": "/path/to/your/project"
"files" : [
{
"source" : "/*.csv",
"translation" : "/%two_letters_code%/%original_file_name%",
# Defines 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_identifier": "your-project-identifier"
"api_key": "54e01e81--your-api-key--f6a2724a" #can be found in your project settings page
"base_path": "/home/website"
"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_identifier": "your-project-identifier"
"api_key": "54e01e81--your-api-key--f6a2724a" #can be found in your project settings page
"base_path": "/home/android-app"
"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})”. A commit_message paraméterrel hozzáadhat Git címkéket, hogy kihagyja az építéseket, teszteket adjon hozzá, stb.
Minta:
"base_path": "/home/office/source-code"
"commit_message": "[ci skip]"
"files": [
{
"source" : "/resources/en/*.json", #source files filter
"translation" : "/resources/%two_letters_code%/%original_file_name%" #where translations are stored
}
]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", #source files filter
"translation" : "/resources/%two_letters_code%/%original_file_name%" #where translations are stored
}
]Alapértelmezés szerint az összes nyelv exportálásra kerül. Ha néhány konkrét nyelvet kíván exportálni, használja az export_languages paramétert, hogy meghatározza azokat.
Minta:
"base_path": "/home/office/source-code"
"export_languages": [
"ru",
"uk",
"ja"
]
"files": [
{
"source" : "/resources/en/*.json", #source files filter
"translation" : "/resources/%two_letters_code%/%original_file_name%" #where translations are stored
}
]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.