Skip to main content

Překlady akcí do dalších jazyků

Překlady Flexideo akcí do dalších jazyků

Technická implementační dokumentace k vícejazyčným akcím ve Flexideo, jak docílit překladu akce do dalších jazyků, než-li je ten pro danou aplikaci výchozí.

1. Předpoklady pro vícejazyčnou aplikaci​

1.1 Aktivace vícejazyčnosti instance​

  • Aby bylo možné překlápět akce (a obecně rozhraní aplikace) do více jazyků, musí být samotná instance Flexidea nastavená jako vícejazyčná.

  • Toto se nastavuje v replikátoru, hned v úplně první volbě (A1).

  • Do konfigurace se přidávají další jazyky pomocí jazykových kódů (např. cs, en, sk atd.).

  • Po první replikaci s touto novou konfigurací se instance „přepne“ do režimu multilang:

  • Každá část aplikace (přehled, dokument, akce…) se pak dá překládat do kteréhokoli z definovaných jazyků.

  • Rozhraní aplikace se poté uživateli zobrazuje podle jazyku, který má na sobě nastavený

Poznámka: minimálně dvě aplikace na tento režim už čekají, takže jde o živou věc a je očekáváno, že se překlepy a detaily začnou ladit.

2. Co přesně se překládá u akce​

V akci rozlišujeme dvě oblasti, které řešíme z pohledu překladu:

  • Hlavička akce (header)

  • Název akce (štítek)

  • Popis akce

  • Vstupní parametry akce (labely těch parametrů)

  • Tělo akce (obsah / logika / uzly v akci)

  • Texty pro uživatele (např. texty e-mailů)

  • Popisky větví, hlášky, texty chyb apod.

  • Jakékoliv další textové hodnoty, které akce generuje a posílá dál (např. e-mail klientovi)

Tyto dvě části (hlavička vs tělo) se překládají jinak. To je klíčové. Viz kapitola 7.

3. Překlad hlavičky akce​

3.1 Přepnutí akce do režimu překladu

  • V editoru akce je nahoře přepínač jazyka (vlaječka).

  • Když přepnu na jiný jazyk (např. z cs na en), začnou se zvýrazňovat prvky, které očekávají překlad.

3.2 Jak to vypadá v UI při překladu

  • Všechny prvky, které chybí přeložit pro daný jazyk, se označí červeně.

  • Typicky:

  • Název akce

  • Popis akce

  • Popisy vstupních parametrů akce (labely polí, která COMEX uživateli ukazuje při spuštění akce)

3.3 Proč se překládá právě tohle

  • Když uživatel spustí akci z rozhraní (COMEX), zobrazí se mu dialog/modal:

  • Nadpis = název akce

  • Popis = text akce / instrukce

  • Vstupy = jednotlivé parametry, které má předat

  • Tyto informace musí být pro uživatele v jeho jazyce.

3.4 Validace překladu hlavičky

  • Dokud je prvek červený, překlad chybí.

  • Pokud není vyplněný popis ani v primárním jazyce (např. ani v češtině), editor by si překlad neměl vynucovat (poznámka zazněla: možná by to nemělo vyžadovat, pokud původní popis není vůbec vyplněný, takže to má Péťa K za úkol).

  • Po doplnění překladu se položka označí jako vyřešená.

4. Překlad těla akce​

4.1 Co je „tělo akce“​

  • Větve akce, uzly, logika, proměnné, sestavení obsahu e-mailu, apod.

  • Příklad: akce „Odeslat e-mail“ má:

  • Příjemce

  • Předmět

  • Tělo e-mailu („Dobrý den, toto je systém…“)

  • Další doplňující uzly

4.2 Princip: jazyková varianta obsahu

  • V těle akce se překládají konkrétní textové uzly (např. text e-mailu).

  • Pokud přepnu akci do jazyka en, všechny texty, které mají být vícejazyčné, zčervenají a čekají svou 'en' variantu.

4.3 Rozdíl proti hlavičce akce

  • Hlavička akce a parametry jsou čistě “UI pro člověka, který teď akci spouští”.

  • Tělo akce může být určeno jinému příjemci než aktuálně přihlášenému uživateli (např. klientovi v jiném jazyce).

  • To znamená, že výběr jazyka pro tělo akce nemusí vycházet z jazyka přihlášeného uživatele. Tohle je zásadní.

5. Řízení jazyka v těle akce pomocí proměnné (vlaječky)​

Tady přichází ten hlavní mechanismus.

5.1 Logika „vlaječky“​

  • V rámci akce si vytvoříme proměnnou (uzel s hodnotou), např. proLang.

  • Název proměnné je libovolný, důležitá je její funkce.

  • Na této proměnné zapneme speciální přepínač „určuje jazyk v překladu“.

  • V UI se to projeví ikonou vlaječky.

  • Po zapnutí tím říkáme: „Tahle proměnná definuje jazyk pro překlady všech potomků dané větve.“

5.2 Jak to funguje hierarchicky​

  • Cokoliv, co je pod touto proměnnou (její přímí potomci v rámci akce), je potenciálně vícejazyčné.

  • Celý podstrom pod tímto bodem se tedy začne brát jako vícejazyčný kontext.

  • Tj. pokud je někde text „Dobrý den…“, Flexideo teď ví, že z toho musí být varianta cs, en, sk atd.

5.3 Co musí mít proměnná s vlaječkou za hodnotu​

  • Do té proměnné se musí dostat jazykový kód, např. cs, en, sk…

  • Tenhle kód určuje, která jazyková mutace se má zrovna použít při běhu akce.

5.4 Odkud ten jazykový kód vezmeme​

Varianty:

  • Jazyk aktuálního uživatele

  • Uživatel má ve své definici kolonku „jazyk“.

  • Ta je jednou z tzv. mapovaných kolonek (stejný typ jako login, heslo atd.).

  • Pokud tam má cs, použijeme cs.

  • Jazyk klienta / adresáta / smlouvy / kontextového dokumentu

  • Pokud posíláme upomínku klientovi, může se jazyk vzít ze smlouvy › z klienta › z pole „jazyk preferované komunikace“.

  • Tím docílíme toho, že třeba český obchodník posílá anglickému klientovi automaticky anglický text.

  • Ručně / logikou akce

  • Implementátor může jazyk určit i explicitně, třeba „v pondělí vždy posílám česky a v úterý slovensky“, prostě jak chce.

  • Systém nevnucuje, že jazyk musí být nutně „jazyk přihlášeného uživatele“.

5.5 Shrnutí chování při běhu akce​

  • Akce se spustí.

  • Načte se hodnota proměnné označené vlaječkou (např. proLang = "en").

  • Pro všechny uzly pod touto proměnnou se použije varianta textu odpovídající "en".

  • Pokud mám přeložené cs, en, sk, ale aktuální hodnota proLang je "en", tak se vybere anglická varianta.

6. Zapínání a vypínání překladu na jednotlivých uzlech (zeměkoule)​

V editoru akce vidím u uzlů ikonu „zeměkoule“ (glóbus). Ta určuje, jestli se

  • daný uzel překládá,

  • dědí režim překladu

  • nebo je překlad zakázaný.

6.1 Stav „modrá zeměkoule“​

  • Význam: „překládáme“.

  • Uzel musí mít vyplněny jazykové varianty.

  • Pokud varianta chybí, editor na to „nadává“ (validace).

  • Modrá zeměkoule tedy vynucuje překlad.

6.2 Stav „šedivá zeměkoule“​

  • Význam: „dělám to, co dělá rodič“.

  • Tzn. uzel dědí nastavení překladu z nejbližšího předka, který má modrou (překládáme) nebo přeškrtnutou (nepřekládáme).

  • Šedá je výchozí stav nově vytvořených uzlů.

  • V případě, že se nenajde předek s modrou nebo přeškrtnutou zeměkoulí, výchozí stav je "překládáme"

6.3 Stav „přeškrtnutá zeměkoule“ / vypnutý překlad​

  • Význam: „nepřekládáme tento uzel ani jeho potomky“.

  • Prakticky tím říkám: obsah tady zůstává v jednom jazyce, varianta se nevytváří.

  • Všichni potomci to automaticky zdědí jako „nepřekládáme“, pokud si to někde níž znovu nevynutím.

6.4 Dědičnost​

  • Pokud na nějakém uzlu nastavím „nepřekládáme“, všichni potomci se šedou zeměkoulí tuto hodnotu dědí.

  • Pokud pak u konkrétního potomka znovu ručně zapnu „modrá zeměkoule“, ten jeden potomek (a jeho podstrom) se zase stane „překládáme“, i když rodič překládání zakázal.

6.5 Typické použití​

  • Chci přeložit jenom text e-mailu, ale nechci řešit překlady technických částí hlavičky dokumentu ›

  • Na kořen větve s technickými informacemi dám „nepřekládáme“.

  • Na větev s e-mailem dám „překládáme“ (modrá).

  • Nebo naopak: chci defaultně překládat všechno (modrá), ale konkrétní část dat (např. interní logy, ID, checksumy) nechci překládat › dám na ten uzel „nepřekládáme“.

7. Rozdíl mezi hlavičkou akce a tělem akce (zásadní)​

Tohle je důležité pro všechny implementátory:

7.1 Hlavička akce​

  • Obsahuje:

  • Název akce

  • Popis akce

  • Vstupní parametry (labely)

  • Použití:

  • Zobrazuje se v COMEXu v modalu při spouštění akce.

  • Je vždy v jazyce přihlášeného uživatele, který akci právě spouští.

  • Jazyk:

  • Jazyk se bere čistě z uživatele, který na to kouká.

  • Uživatel „česky mluvící“ = uvidí česky.

  • Uživatel „anglicky mluvící“ = uvidí anglicky.

  • Není potřeba specifikovat logiku přepínání jazyka – COMEX to řeší za nás jako součást UI.

7.2 Tělo akce​

  • Obsahuje:

  • Samotné kroky/uzly akce

  • Vygenerované texty (e-mail klientovi, chybové hlášení, potvrzení apod.)

  • Použití:

  • Běží buď „z COMEXu“ (uživatelsky spuštěné), nebo může běžet úplně na pozadí (server-side).

  • Texty z těla akce typicky konzumuje někdo jiný než spouštějící uživatel – např. klient (e-mail), partner, externí systém.

  • Jazyk:

  • Není pevně dán přihlášeným uživatelem.

  • Určuje se podle logiky, kterou nastavíme pomocí proměnné s vlaječkou (viz kapitola 5).

  • Jazyk může jít z klienta, ze smlouvy, z příjemce mailu atd.

  • Výsledek:

  • Český obchodník může posílat e-mail anglicky mluvícímu klientovi › hlavička akce mu běží česky (on je Čech), ale e-mail odejde v angličtině (jazyk z klienta).

Tohle chování je úmyslné a je to správně.

8. Praktické scénáře​

8.1 Posílám e-mail klientovi​

  • Udělám akci „Odeslat e-mail“.

  • V akci mám proměnnou např. 'proLang' s vlaječkou.

  • Do proLang vložím jazyk klienta (např. z jeho karty).

  • V e-mailovém těle mám přepnuté uzly na „překládáme“ (modrá zeměkoule).

  • Pro jazyk en doplním anglickou verzi textu.

  • Akce se spustí -> klient dostane anglický obsah.

8.2 Upomínka ze smlouvy​

  • Tvořím automatickou upomínku ve více jazycích.

  • Jazyk vezmu ne z uživatele, který akci spustil, ale přímo ze smlouvy/klienta (třeba klient má jazyk sk).

  • Do proměnné s vlaječkou uložím 'sk'.

  • Výstup e-mailu (tělo akce) vyjede slovensky.

8.3 Více jazykových logik v jedné akci​

  • Akce může potřebovat dvě různé jazykové logiky najednou.

  • Například:

  • Část je „pro uživatele“ (interní instrukce, log), ta jede podle jazyka uživatele.

  • Část je „pro klienta“ (mailová textace), ta jede podle jazyka klienta.

  • Lze to vyřešit tak, že:

  • V kořenové větvi akce nastavím vlaječku na jazyk uživatele.

  • V jedné podvětvi (např. větev „komunikace klientovi“) nastavím znovu vlastní vlaječku, která bere jazyk z klienta.

  • Výsledek: různé části akce mohou překládat texty podle různých jazykových kontextů.

Pozor: pokud se někde snažím vložit víc vlaječek „nad sebe“ a není to dovoleno, editor mě na to má upozornit. Pokud by narazilo na limit/fail, eskalace vývojářům.

9. Co dělat, když nestačí standardní překladový mechanismus​

Někdy nestačí jen „stejný text v jiném jazyce“. Potřebuju jiný slovosled, jinou skladbu vět, jiný pořadí proměnných. Typický příklad: tělo e-mailu se skládá z bloků:

  • text

  • číslo faktury

  • další text

  • jméno adresáta

  • datum

… a v angličtině to chci v jiném pořadí než v češtině.

Řešení je:

9.1 Vypnout překlad pro ten konkrétní obsahový uzel​

  • Na daném uzlu dám „nepřekládáme“ (přeškrtnutá zeměkoule).

  • Tím říkám: tady nechci generický překlad po částech.

9.2 Sestavit jazykové varianty ručně​

  • Udělám si uzel typu „varianta“, kde si podmínkami zajistím různé výstupy pro různé jazyky.

  • Prakticky: použiju logiku větvení / conditions, skoro jako kdyby překladový mechanismus vůbec neexistoval.

  • Tj. ručně si poskládám tělo e-mailu pro cs a ručně zvlášť pro en, i s jiným pořadím polí.

Tohle je doporučený postup pro složitější jazykové konstrukce.

10. Validace a hranice systému​

  • Systém aktuálně validuje, jestli jsou vyplněné povinné překlady (červené prvky), ale ještě tam jsou některé nedodělky validací – tj. občas to „ještě úplně nefunguje“, ale to se bude ladit.

  • Pokud přepnu uzel do režimu „překládáme“ (modrá), ale nic tam pro daný jazyk nevyplním, systém má být na mě „naštvaný“ a hlásit, že překlad chybí.

  • Pokud nastavím „nepřekládáme“, tak se ten uzel tváří jako vyřešený a překlad se nevyžaduje.

11. Napojení na COMEX a XDS​

11.1 Přehledy a akce v COMEXu​

  • To, že akce, přehledy a dokumenty lze přeložit, je poslední dílek skládačky pro plně vícejazyčnou aplikaci – podle toho, kdo se dívá.

  • Přehledy, formuláře a akce se už dnes dají překlápět (hlavičky a obsahy).

11.2 Hlavičky dokumentů v XDS​

  • Pokud mám dokument definovaný v XDS aplikaci, která má víc než jeden jazyk:

  • Do hlavičky dokumentu se dá přidat přeložený název.

  • Příklad: dokument faktura má v hlavičce cs="Faktura", en="Invoice".

  • Jakmile v hlavičce dokumentu uvedu přeloženou variantu, replikátor začne kontrolovat, jestli jsou přeložené i ostatní labely a popisy v dokumentu pro tento jazyk:

  • Labely polí

  • Popisy

  • Obsahy náhledů (form, preview, tisk)

  • Jinými slovy: pokud řeknu „tenhle dokument má i angličtinu“, tak tím zároveň říkám „musím mít angličtinu všude uvnitř toho dokumentu“.

11.3 Co všechno se překládá v rámci XDS/COMEX vrstvy​

  • Formuláře (form)

  • Tiskové náhledy

  • Tabulky / přehledy

  • Akce

… a právě teď jsme řešili akce do této hloubky.

12. Postup implementátora krok za krokem (doporučený workflow)​

  • V replikátoru (A1) přidej další jazyk(y) a proveď replikaci.

  • Ověř, že uživatelé a/nebo klienti mají vyplněný jazyk (pole „jazyk“ u uživatele/klienta).

  • V akci nahoře přepni vlaječku na nový jazyk a přelož:

  • Název akce

  • Popis akce

  • Labely vstupních parametrů

  • V těle akce:

  • Identifikuj části, které budou generovat text směrem ven (např. e-mail).

  • U kořene větve, která ty texty řeší, vlož proměnnou s vlaječkou › tahle proměnná musí obsahovat jazykový kód, který chceš v rámci této větve používat.

  • Nastav zeměkoule:

  • Kde potřebuji vícejazyčný obsah › modrá (překládáme).

  • Kde je to technické a nechci to překládat › přeškrtnout (nepřekládáme).

  • Pro každý jazyk doplň varianty textů (červené prvky musí „zezelenat“/odčervenat).

  • Pokud je potřeba úplně jiný slovosled nebo úplně jiná struktura obsahu:

  • Na takové větvi vypni překlad (přeškrtnout zeměkouli).

  • Udělej si ručně varianty pomocí podmínek podle jazyka.

  • Otestuj akci:

  • Scénář 1: spuštění jako já (můj jazyk)

  • Scénář 2: výstup klientovi s jiným jazykem

  • Scénář 3: případ, kde nechci překládat určitou část (má zůstat vždy stejná)