Konfigurációs fájl

Megjegyzés: Ha a Crowdin CLI régi verzióját használja (<= 0.5.5), akkor több információt kaphat ez ügyben itt: Crowdin Github.

Tartalom

Bevezetés

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 generate

Konfigurációs fájl felépítése

Az é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:

  • Fájl elején adatok a projekt hitelesítőiről, preferenciáiról és hozzáférési információiról
  • Egy elem a fájlok tömbjében, amely leírja a kezelendő fájlok halmazát
  • A Source - mely meghatározza a forrásfájlokra vonatkozó szűréseket - és a Translation - mely megmondja hogy hol kerüljenek tárolásra a fordítások mezők szükségesek, vagy hogy hol keresse a már rendelkezésre álló fordításokat - mezők szükségesek a fájlok tömbjében, ha fel kívánja őket tölteni a CLI beállításával

Nézze meg az API integráció beállítása cikket, hogy megtanulja, hol találja a projekt hitelesítő adatait.

Egy egyszerű konfigurációs fájl írása

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 sources

Fordítások letöltése Crowdinról és a megfelelő helyre tenni őket:

$ crowdin download

API hitelesítő adatok a környezeti változókból

Az 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_PATH

Ha 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 Projekt konfiguráció és az API hitelesítő adatok szétválasztása

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 sources

Általános konfiguráció

A 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.

Helyőrzők

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%”.

Helyettesítő karakterek használata

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
  1. példa Helyettesítő karakterek használata a forrás elérési útjában:
#........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%"
  }
]
  1. példa Helyettesítő karakterek használata a fájlok figyelmen kívül hagyásához:
#........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
    ]
  }
]

Nyelv hozzárendelése

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.

Fordítás fájlok átnevezése

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.

Fájlok és könyvtárak figyelmen kívül hagyása

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"
    ]
  }
]

Többoszlopos CSV

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"
  }
]

Könyvtárszerkezet mentése a szerverre

"preserve_hierarchy": true

Pé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

Fájlok feltöltése megadott útvonalon, megadott típussal

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.

Figyelem! A 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%"
  }
]

Módosított karakterláncok frissítése

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"
  }
]

Fordítások feltöltése

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:

  • -l, –language=language_code - határozza meg azokat a fordításokat, amelyeket fel kell tölteni a Crowdinba. Alapértelmezés szerint a fordítások feltöltése a projekt minden célnyelvére történik. (Crowdin nyelvkódok)
  • –[no-]import-duplicates - határozza meg, hogy a fordítás akkor is hozzáadandó e, ha azonos fordítás már létezik a Crowdin projektben
  • –[no-]import-eq-suggestions - határozza meg, hogy a fordítást hozzáadja e, ha az egyenlő forrás-karakterlánccal a Crowdin projektben
  • –[no-]auto-approve-imported - automatikusan jóváhagyja a feltöltött fordításokat

További lehetőségek az XML fájlokhoz

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
    ]
  }
]

Védett idézőjelek beállításai a .properties fájlformátumhoz

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:

  • 0 - ne védje az aposztrófot
  • 1 - aposztróf védése egy másik aposztróffal
  • 2 - aposztróf védése fordított perjellel
  • 3 - aposztróf védése egy másik aposztróffal csak azokban a karakterláncokban, amelyek változót tartalmaznak ( {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
  }
]

Példa konfigurációk

CSV fájlok feltöltése API segítségével

"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"
  }
]

GetText projekt

"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"
      }
    }
  }
]

Android projekt

"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"
      }
    }
  }
]

Konfigurációs fájl a VCS integrációkhoz

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 projekt hitelesí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ó.

Leíró üzenet paraméter a VCS integrációkhoz

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
  }
]

Nyelvek exportálási paraméterei a VCS integrációkhoz

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ég kérése

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.

Lásd még

Hasznos volt ez a cikk?