Konfigurációs fájl

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. Ez a konfiguráció szakaszokba rendeződik, amelyek tartalmazzák 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 írja meg 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 következő parancs futtatásával hozhatja létre:

$ crowdin generate

A cikk célja, hogy segítsen a Crowdin CLI beszerzésében, beállításában és futtatásában. Ha egyszer megfelelően beállította a Crowdin CLI-t, akkor nem kell újra átnéznie ezt az oldalt, hacsak nem indít egy másik projektet.

Konfigurációs fájl struktúrája

Az érvényes Crowdin CLI konfigurációs fájl a következő struktúrával rendelkezik:

• Az Ön Crowdin projekt hitelesítő adatai, a projekt preferenciái és a hozzáférési információk (ezek a YAML fájl élén)
• Pontosan egyik elem a fájlok tömbjében, amely leírja a kezelendő fájlok halmazát
• Legalább a Forrás és a Fordítás mezőket a fájlok tömbjében, amelyek meghatározzák a forrásfájlok szűrőit és az utasításokat, hogy hol kerüljenek a lefordított fájlok tárolásra (továbbá, hogy hol kell keresni a fordításokat, ha első alkalommal szeretné feltölteni őket)

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

"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 Crowdinba való feltöltése csak egy parancssori hívás:

$ crowdin upload sources

Fordítások beszerzése a Crowdinból és azok megfelelő helyre történő másolása:

$ 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 kiszivároghat 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

FIGYELEM: 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:

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”. Mindegyiküket a %two_letters_code% helyőrző képviseli. 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 szerveren

"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 a megadott útvonalra a 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 hasznos, 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.

Példa a konfigurációs fájlra 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

Példa a konfigurációs fájlra az 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 is importálásra kerülnek, 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értelmezetten a fordítások az összes projekt célnyelvre feltöltésre kerül. (Crowdin nyelvkódok)
• –[no-]import-duplicates - határozza meg, hogy a fordítást hozzáadja e, ha a Crowdin projektben már létezik ugyanaz a fordítás
• –[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

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 funkció 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 paraméter 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
  }
]

Konfiguráció mintá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"
      }
    }
  }
]

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

• Verziók kezelése
• Crowdin CLI