snapshot of https://github.com/twentyhq/twenty.git (main, 2026-09-17; blobs > 131072B omitted)

packages/twenty-docs/l/cs/developers/extend/apps/operations/cli.mdx

@@ -0,0 +1,131 @@
+---
+title: CLI
+description: příkazy `yarn twenty` pro spouštění funkcí, streamování logů, správu instalací aplikací a přepínání vzdálených serverů.
+icon: terminal
+---
+
+CLI `yarn twenty` je vaše rozhraní ke všemu, co souvisí s aplikací. Úplný seznam příkazů:
+
+| Příkaz                                          | K čemu slouží                                                                       | Zdokumentováno v                                                                                         |
+| ----------------------------------------------- | ----------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
+| `dev`                                           | Sleduje zdrojové soubory a živě synchronizuje změny                                 | [Rychlý start](/l/cs/developers/extend/apps/getting-started/quick-start)                                      |
+| `plán`                                          | Náhled změn metadat bez jejich aplikování                                           | [Synchronizace a obnovení](/l/cs/developers/extend/apps/operations/sync-and-recovery#previewing-changes-plan) |
+| `použít`                                        | Aplikovat změny metadat po zobrazení plánu                                          | [Synchronizace a obnovení](/l/cs/developers/extend/apps/operations/sync-and-recovery)                         |
+| `dev:build`                                     | Zkompilovat aplikaci a vygenerovat API klienta (`--tarball` pro zabalení do `.tgz`) | [Publikování](/l/cs/developers/extend/apps/operations/publishing)                                             |
+| `dev:typecheck`                                 | Spustit kontrolu typů TypeScriptu                                                   | [Testování](/l/cs/developers/extend/apps/operations/testing)                                                  |
+| `dev:add`                                       | Vytvořit kostru nové entity                                                         | [Scaffolding](/l/cs/developers/extend/apps/getting-started/scaffolding)                                       |
+| `dev:generate-client`                           | Znovu vygenerovat typovaného API klienta                                            | tato stránka                                                                                             |
+| `dev:function:exec` / `dev:function:logs`       | Spustit funkce a streamovat jejich logy                                             | tato stránka                                                                                             |
+| `dev:translations-extract`                      | Extrahovat přeložitelné řetězce do katalogů v `locales/`                            | [Překlady](/l/cs/developers/extend/apps/operations/translations)                                                |
+| `dev:catalog-sync`                              | Spustit synchronizaci katalogu tržiště                                              | [Publikování](/l/cs/developers/extend/apps/operations/publishing#how-marketplace-discovery-works)             |
+| `app:publish` / `app:install` / `app:uninstall` | Životní cyklus vydání                                                               | [Publikování](/l/cs/developers/extend/apps/operations/publishing) a tato stránka                              |
+| `docker:*`                                      | Spravovat kontejner lokálního serveru Twenty                                        | [Lokální server](/l/cs/developers/extend/apps/getting-started/local-server)                                   |
+| `remote:*`                                      | Spravovat připojení k serveru                                                       | tato stránka                                                                                             |
+
+Každý příkaz přijímá `-r, --remote \<name>` pro zacílení na konkrétní vzdálené připojení místo výchozího.
+
+## Spouštění funkcí (`yarn twenty dev:function:exec`)
+
+Spusťte logickou funkci ručně bez vyvolání přes HTTP, cron nebo databázovou událost:
+
+```bash filename="Terminal"
+# Execute by function name
+yarn twenty dev:function:exec -n create-new-post-card
+
+# Execute by universalIdentifier
+yarn twenty dev:function:exec -u e56d363b-0bdc-4d8a-a393-6f0d1c75bdcf
+
+# Pass a JSON payload
+yarn twenty dev:function:exec -n create-new-post-card -p '{"name": "Hello"}'
+
+# Execute the install and uninstall hooks
+yarn twenty dev:function:exec --postInstall
+yarn twenty dev:function:exec --preInstall
+yarn twenty dev:function:exec --uninstall
+```
+
+## Zobrazení logů funkcí (`yarn twenty dev:function:logs`)
+
+Streamujte výstupní logy běhu logických funkcí vaší aplikace:
+
+```bash filename="Terminal"
+# Stream all function logs
+yarn twenty dev:function:logs
+
+# Filter by function name
+yarn twenty dev:function:logs -n create-new-post-card
+
+# Filter by universalIdentifier
+yarn twenty dev:function:logs -u e56d363b-0bdc-4d8a-a393-6f0d1c75bdcf
+```
+
+<Note>
+To se liší od `yarn twenty docker:logs`, který zobrazuje logy kontejneru Docker. `yarn twenty dev:function:logs` zobrazuje logy běhu funkcí vaší aplikace ze serveru Twenty.
+</Note>
+
+## Generování typovaného klienta (`yarn twenty dev:generate-client`)
+
+Znovu vygenerujte typovaného klienta API (`twenty-client-sdk`) ze schématu aktivního vzdáleného serveru, bez sestavování nebo synchronizace aplikace. Použijte jej k získání typovaného klienta v libovolném projektu – například backendové služby v samostatném repozitáři – který komunikuje s vaší instancí Twenty:
+
+```bash filename="Terminal"
+# In your project (no Twenty app definition required)
+yarn add twenty-sdk twenty-client-sdk
+
+# Connect to the Twenty instance to generate the client from
+yarn twenty remote:add
+
+# Generate the typed client into node_modules/twenty-client-sdk
+yarn twenty dev:generate-client
+```
+
+Poté klienta importujte ve svém kódu:
+
+```typescript
+import { CoreApiClient } from 'twenty-client-sdk/core';
+```
+
+Spusťte příkaz znovu pokaždé, když se změní váš datový model, abyste aktualizovali vygenerované typy.
+
+<Note>
+Klient je vygenerován uvnitř `node_modules`, takže není verzován spolu s vaším kódem. Spusťte `yarn twenty dev:generate-client` po každé instalaci (například ve skriptu `postinstall` nebo v CI).
+</Note>
+
+## Odinstalace aplikace (`yarn twenty app:uninstall`)
+
+Odeberte svou aplikaci z aktivního pracovního prostoru:
+
+```bash filename="Terminal"
+yarn twenty app:uninstall
+
+# Skip the confirmation prompt
+yarn twenty app:uninstall --yes
+```
+
+## Správa vzdálených serverů
+
+**Remote** je server Twenty, ke kterému se vaše aplikace připojuje. Během nastavení jej generátor kostry automaticky vytvoří. Můžete kdykoli přidat další vzdálené servery nebo mezi nimi přepínat.
+
+```bash filename="Terminal"
+# Add a new remote (opens a browser for OAuth login)
+yarn twenty remote:add
+
+# Connect to a local Twenty server (auto-detects port 2020 or 3000)
+yarn twenty remote:add --local
+
+# Add a remote non-interactively (useful for CI)
+yarn twenty remote:add --url https://your-twenty-server.com --api-key $TWENTY_API_KEY --as my-remote
+
+# List all configured remotes
+yarn twenty remote:list
+
+# Set the active remote
+yarn twenty remote:use <name>
+
+# Check that the active remote's authentication is still valid
+yarn twenty remote:status
+
+# Remove a remote
+yarn twenty remote:remove <name>
+```
+
+Vaše přihlašovací údaje jsou uloženy v `~/.twenty/config.json`.

packages/twenty-docs/l/cs/developers/extend/apps/operations/overview.mdx

@@ -0,0 +1,32 @@
+---
+title: Přehled
+description: Sestavte, otestujte a doručte svou aplikaci — příkazy CLI, integrační testy, CI a publikování na server nebo do npm.
+icon: rocket
+---
+
+**Provozní vrstva** je všechno, co děláte *na* své aplikaci, nikoli *pomocí* ní: spouštění příkazů CLI, provádění integračních testů proti reálnému serveru Twenty, konfigurace CI a vydávání verzí — buď jako tarball nasazený na jednom serveru, nebo jako balíček npm uvedený v Marketplace.
+
+```text
+   develop ─▶ test ─▶ build ─▶ deploy / publish
+   ───────    ────    ─────    ─────────────────
+   yarn       yarn    yarn     yarn twenty app:publish --private  (tarball → one server)
+   twenty     test    twenty
+   dev                dev:build    yarn twenty app:publish         (npm → marketplace)
+```
+
+## V této části
+
+<CardGroup cols={2}>
+  <Card title="CLI" icon="terminal" href="/l/cs/developers/extend/apps/operations/cli">
+    Referenční přehled `yarn twenty` — exec, logs, uninstall, remotes.
+  </Card>
+  <Card title="Synchronizace a obnovení" icon="compass" href="/l/cs/developers/extend/apps/operations/sync-and-recovery">
+    Který příkaz kdy použít, jak číst diff synchronizace a postup obnovy.
+  </Card>
+  <Card title="Testování" icon="flask" href="/l/cs/developers/extend/apps/operations/testing">
+    Nastavení Vitestu, integrační testy, kontrola typů, workflow CI.
+  </Card>
+  <Card title="Publikování" icon="upload" href="/l/cs/developers/extend/apps/operations/publishing">
+    Sestavit, nasadit tarball, publikovat do npm, nainstalovat.
+  </Card>
+</CardGroup>

packages/twenty-docs/l/cs/developers/extend/apps/operations/publishing.mdx

@@ -0,0 +1,293 @@
+---
+title: Publikování
+icon: upload
+description: Distribuujte svou aplikaci Twenty do Marketplace nebo ji nasaďte interně.
+---
+
+## Přehled
+
+Jakmile je vaše aplikace [sestavena a otestována lokálně](/l/cs/developers/extend/apps/getting-started/concepts), máte dvě cesty, jak ji distribuovat:
+
+* **Nasaďte tarball** — nahrajte svou aplikaci přímo na konkrétní server Twenty pro interní nebo soukromé použití.
+* **Publish to npm** — uveďte svou aplikaci v Marketplace Twenty, aby ji mohl kterýkoli pracovní prostor objevit a nainstalovat.
+
+Obě cesty začínají stejným krokem **build**.
+
+## Sestavení vaší aplikace
+
+Spusťte příkaz build ke zkompilování své aplikace a k vygenerování souboru `manifest.json` připraveného k distribuci:
+
+```bash filename="Terminal"
+yarn twenty dev:build
+```
+
+Tím se zkompilují zdrojové soubory TypeScriptu, transpilují logické funkce a frontendové komponenty a vše se zapíše do `.twenty/output/`. Přidejte `--tarball`, abyste také vytvořili balíček `.tgz` pro ruční distribuci nebo příkaz publish.
+
+## Nasazení na server (tarball)
+
+U aplikací, které nechcete zpřístupnit veřejně — proprietární nástroje, integrace pouze pro enterprise nebo experimentální buildy — můžete nasadit tarball přímo na server Twenty.
+
+### Předpoklady
+
+Před nasazením potřebujete nakonfigurovaný vzdálený cíl směřující na cílový server. Vzdálené cíle ukládají adresu URL serveru a přihlašovací údaje lokálně v `~/.twenty/config.json`.
+
+Přidat vzdálený cíl:
+
+```bash filename="Terminal"
+yarn twenty remote:add --url https://your-twenty-server.com --as production
+```
+
+### Nasazení
+
+Sestavte a nahrajte svou aplikaci na server v jednom kroku:
+
+```bash filename="Terminal"
+yarn twenty app:publish --private
+# To deploy to a specific remote:
+# yarn twenty app:publish --private --remote production
+```
+
+### Sdílení nasazené aplikace
+
+Aplikace ve formě tarball nejsou uvedeny ve veřejném tržišti, takže je ostatní pracovní prostory na tomtéž serveru procházením neobjeví. Chcete-li sdílet nasazenou aplikaci:
+
+1. Přejděte do **Nastavení > Aplikace > Registrace** a otevřete svou aplikaci
+2. Na kartě **Distribuce** klikněte na **Zkopírovat odkaz ke sdílení**
+3. Sdílejte tento odkaz s uživateli v jiných pracovních prostorech — zavede je přímo na instalační stránku aplikace
+
+Odkaz ke sdílení používá základní adresu URL serveru (bez jakékoli subdomény pracovního prostoru), takže funguje pro libovolný pracovní prostor na serveru.
+
+### Správa verzí
+
+Při aktualizaci již nasazené tarballové aplikace server vyžaduje, aby hodnota `version` v `package.json` byla **přísně vyšší** (podle řazení [semver](https://semver.org)) než aktuálně nasazená verze. Opětovné nasazení stejné verze nebo odeslání nižší verze je odmítnuto ještě před uložením tarballu — v CLI uvidíte chybu `VERSION_ALREADY_EXISTS`.
+
+Chcete-li vydat aktualizaci:
+
+1. Zvyšte hodnotu pole `version` v souboru `package.json` (např. `1.2.3` → `1.2.4`, `1.3.0` nebo `2.0.0`)
+2. Spusťte `yarn twenty app:publish --private` (nebo `yarn twenty app:publish --private --remote production`)
+3. Pracovní prostory, které mají aplikaci nainstalovanou a mají pro ni povolené automatické aktualizace (na kartě Nastavení aplikace), jsou na pozadí aktualizovány automaticky; ostatní uvidí dostupnou aktualizaci ve svém nastavení
+
+<Note>
+Předběžné tagy fungují podle očekávání: zvýšení z `1.0.0-rc.1` → `1.0.0-rc.2` je povoleno a finální vydání jako `1.0.0` je správně rozpoznáno jako vyšší než `1.0.0-rc.5`. Verze v `package.json` musí být platným řetězcem semver.
+</Note>
+
+{/* TODO: add screenshot of the Upgrade button */}
+
+### Kompatibilita verze serveru
+
+Pokud vaše aplikace používá funkci zavedenou v konkrétní verzi serveru Twenty (například poskytovatelé OAuth přidaní ve verzi 2.3.0), měli byste deklarovat minimální verzi serveru, kterou vaše aplikace vyžaduje, pomocí pole `engines.twenty` v `package.json`:
+
+```json filename="package.json"
+{
+  "name": "twenty-my-app",
+  "version": "1.0.0",
+  "engines": {
+    "node": "^24.5.0",
+    "twenty": ">=2.3.0"
+  }
+}
+```
+
+Hodnota je standardní [rozsah SemVer](https://github.com/npm/node-semver#ranges). Běžné vzory:
+
+| Rozsah                             | Význam                                         |
+| ---------------------------------- | ---------------------------------------------- |
+| `>=2.3.0`                          | Jakýkoli server od verze 2.3.0 výše            |
+| `>=2.3.0 \<3.0.0` | 2.3.0 nebo novější, ale pod další hlavní verzí |
+| `^2.3.0`                           | Stejné jako `>=2.3.0 \<3.0.0` |
+
+**Co se děje při nasazení a instalaci:**
+
+* Pokud je `engines.twenty` nastaveno a verze cílového serveru nevyhovuje rozsahu, nasazení (nahrání tarballu) nebo instalace je odmítnuto chybou `SERVER_VERSION_INCOMPATIBLE` a zprávou, která uvádí jak požadovaný rozsah, tak skutečnou verzi serveru.
+* Pokud `engines.twenty` **není nastaveno**, aplikace je přijata na jakékoli verzi serveru (zpětně kompatibilní se stávajícími aplikacemi).
+* Pokud server nemá nakonfigurované `APP_VERSION`, kontrola se přeskočí.
+
+<Note>
+Server je rozhodující autoritou — ověřuje `engines.twenty` jak při nahrání tarballu, tak při instalaci do pracovního prostoru. Pokud nasazujete tarball mimo standardní proces nebo instalujete z marketplace, server přesto vynucuje kompatibilitu.
+</Note>
+
+## Automatizované CI/CD (předpřipravené workflowy)
+
+Aplikace vygenerované pomocí `create-twenty-app` jsou hned připravené se třemi workflowy GitHub Actions ve složce `.github/workflows/`. CI běží bez jakéhokoli nastavování, CD vyžaduje jediný secret a publikování na npm vyžaduje jednorázové nastavení npm trusted-publisher.
+
+### CI — `ci.yml`
+
+Automaticky spouští integrační testy při každém pushi do `main` a u pull requestů.
+
+**K čemu slouží:**
+
+1. Provede checkout zdrojového kódu vaší aplikace.
+2. Spustí izolovanou testovací instanci Twenty pomocí složené akce `twentyhq/twenty/.github/actions/spawn-twenty-app-dev-test@main` (ekvivalent v CI k `yarn twenty docker:start --test`).
+3. Povolí Corepack, nastaví Node.js podle vašeho `.nvmrc` a nainstaluje závislosti pomocí `yarn install --immutable`.
+4. Spustí `yarn test` a předá `TWENTY_API_URL` a `TWENTY_API_KEY` ze spuštěné instance, aby vaše testy mohly komunikovat se skutečným serverem.
+
+**Konfigurační volby:**
+
+* `TWENTY_VERSION` (env, výchozí hodnota `latest`) — uzamkněte v CI používanou verzi serveru Twenty úpravou této hodnoty v `ci.yml`.
+* Souběžné běhy jsou seskupeny podle `github.ref` a při nových pushích ruší právě probíhající běhy.
+
+Nejsou potřeba žádné secrety — testovací instance je efemérní a existuje pouze po dobu běhu úlohy.
+
+### CD — `cd.yml`
+
+Nasazuje vaši aplikaci na nakonfigurovaný server Twenty při každém pushi do `main` a volitelně také z pull requestu, pokud je přidán štítek `deploy`.
+
+**K čemu slouží:**
+
+1. Provede checkout headu PR (u označených PR) nebo pushnutého commitu.
+2. Spustí `twentyhq/twenty/.github/actions/deploy-twenty-app@main` — ekvivalent v CI k `yarn twenty app:publish --private`.
+3. Spustí `twentyhq/twenty/.github/actions/install-twenty-app@main`, aby se nově nasazená verze nainstalovala do cílového pracovního prostoru.
+
+**Požadovaná konfigurace:**
+
+| Nastavení               | Kde                                                             | Účel                                                                                                 |
+| ----------------------- | --------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
+| `TWENTY_DEPLOY_URL`     | `env` v `cd.yml` (výchozí `http://localhost:3000`)              | Server Twenty, na který se nasazuje. Před prvním použitím to změňte na skutečnou URL vašeho serveru. |
+| `TWENTY_DEPLOY_API_KEY` | GitHub repozitář **Settings → Secrets and variables → Actions** | API klíč s oprávněním k nasazení na cílovém serveru.                                                 |
+
+<Note>
+Výchozí `TWENTY_DEPLOY_URL` `http://localhost:3000` je pouze zástupná hodnota — z runneru hostovaného GitHubem tato adresa nebude dosažitelná. Před povolením CD ji aktualizujte na veřejnou URL vašeho serveru (nebo použijte self-hosted runner s přístupem do sítě).
+</Note>
+
+**Spuštění náhledového nasazení z PR:**
+
+Přidejte k pull requestu štítek `deploy`. Podmínka `if:` v `cd.yml` spustí úlohu pro dané PR s použitím head commitu PR, což vám umožní ověřit změnu na cílovém serveru před sloučením.
+
+### Publish — `publish.yml`
+
+Publikuje vaši aplikaci na npm s doloženým původem, když odešlete tag verze (např. `v1.0.0`), nebo když workflow spustíte ručně na kartě Actions.
+
+**K čemu slouží:**
+
+1. Načte repozitář vaší aplikace, nastaví Node.js a aktualizuje npm (důvěryhodné publikování vyžaduje npm 11.5.1 nebo novější).
+2. Spustí `yarn twenty app:publish`, který sestaví aplikaci a publikuje `.twenty/output` na npm. V CI automaticky přidá `--provenance` a `--access public`, takže ve workflowu nejsou potřeba žádné přepínače.
+
+**Jednorázové nastavení:**
+
+Na npmjs.com otevřete svůj balíček > **Settings → Trusted Publisher** a zaregistrujte tento repozitář s workflowem `publish.yml` (viz [dokumentaci k důvěryhodnému publikování na npm](https://docs.npmjs.com/trusted-publishers)). Publikování s provenance potvrzuje, který repozitář na GitHubu balíček sestavil, a zároveň tak uplatňujete vlastnictví své aplikace na tržišti Twenty.
+
+<Note>
+npm přijímá údaje o původu pouze z **veřejných** zdrojových repozitářů. Pokud publikujete ze soukromého repozitáře, npm odmítne balíček údajů o původu OIDC s chybou `E422 ... Unsupported GitHub Actions source repository visibility: "private"` error. Chcete-li publikovat ze soukromého repozitáře, vypněte prokazování původu nastavením `TWENTY_APP_PUBLISH_DISABLE_PROVENANCE: 'true'` v `env` publikačního kroku (ve vygenerovaném `publish.yml` je uveden zakomentovaný tip):
+
+```yaml filename=".github/workflows/publish.yml"
+      - name: Publish to npm
+        env:
+          TWENTY_APP_PUBLISH_DISABLE_PROVENANCE: 'true'
+        run: yarn twenty app:publish
+```
+</Note>
+
+### Připnutí verzí znovupoužitelných akcí
+
+Workflowy `ci.yml` a `cd.yml` odkazují na znovupoužitelné akce na `@main`, takže aktualizace akcí v repozitáři `twentyhq/twenty` se přeberou automaticky. Pokud chcete deterministická sestavení, nahraďte `@main` v každém řádku `uses:` za commit SHA nebo tag vydání.
+
+## Publikování na npm
+
+Publikování na npm zajistí, že bude vaše aplikace dohledatelná v Marketplace Twenty. Jakýkoli pracovní prostor Twenty může procházet, instalovat a aktualizovat aplikace z Marketplace přímo z UI.
+
+### Požadavky
+
+* Účet na [npm](https://www.npmjs.com)
+* Klíčové slovo `twenty-app` ve vašem poli `keywords` v souboru `package.json` (přidejte ho ručně — ve výchozím nastavení není zahrnuto v šabloně `create-twenty-app`)
+
+```json filename="package.json"
+{
+  "name": "twenty-app-postcard-sender",
+  "version": "1.0.0",
+  "keywords": ["twenty-app"]
+}
+```
+
+### Metadata tržiště
+
+Konfigurace `defineApplication()` podporuje volitelná pole, která určují, jak se vaše aplikace zobrazuje v tržišti. Použijte `logo` a `galleryImages` k odkazování na obrázky ze složky `public/`:
+
+```ts src/application-config.ts
+export default defineApplication({
+  universalIdentifier: '...',
+  displayName: 'My App',
+  description: 'A great app',
+  logo: 'public/logo.png',
+  galleryImages: [
+    'public/screenshot-1.png',
+    'public/screenshot-2.png',
+  ],
+});
+```
+
+Podívejte se na [sekci defineApplication](/l/cs/developers/extend/apps/config/application#marketplace-metadata) na stránce Building Apps pro úplný seznam polí tržiště (`author`, `category`, `aboutDescription`, `websiteUrl`, `termsUrl` atd.).
+
+#### Doporučené rozměry obrázků v galerii
+
+Tržiště zobrazuje `galleryImages` v pevném kontejneru s poměrem stran `8:5` (například `1600×1000 px`).
+
+<Note>
+Obrázky v galerii libovolného poměru stran se zobrazují celé a nikdy se neořezávají, ale cokoli výrazně vyššího nebo užšího než `8:5` bude mít po stranách prázdné pruhy.
+</Note>
+
+#### Limit velikosti obrázku
+
+Soubor `logo` a každý soubor v `galleryImages` nesmí překročit **10 MB**. Větší soubory jsou při přesunu vašich publikovaných souborů na servery marketplace vynechány, takže se nezobrazí.
+
+### Publikování
+
+```bash filename="Terminal"
+yarn twenty app:publish
+```
+
+Chcete-li publikovat pod konkrétním dist-tagem (např. `beta` nebo `next`):
+
+```bash filename="Terminal"
+yarn twenty app:publish --tag beta
+```
+
+### Jak funguje objevování v tržišti
+
+Server Twenty synchronizuje svůj katalog tržiště z registru npm **každou hodinu**.
+
+Synchronizaci můžete spustit okamžitě místo čekání:
+
+```bash filename="Terminal"
+yarn twenty dev:catalog-sync
+# To target a specific remote:
+# yarn twenty dev:catalog-sync --remote production
+```
+
+Metadata zobrazená na tržišti pocházejí z vaší konfigurace `defineApplication()` — viz výše [Metadata tržiště](#marketplace-metadata).
+
+<Note>
+Pokud vaše aplikace nedefinuje `aboutDescription` v `defineApplication()`, tržiště automaticky použije soubor `README.md` vašeho balíčku z npm jako obsah stránky O aplikaci. To znamená, že můžete spravovat jediný soubor README jak pro npm, tak pro tržiště Twenty. Pokud chcete v tržišti jiný popis, explicitně nastavte `aboutDescription`.
+</Note>
+
+### Publikování pomocí CI
+
+Vygenerované workflow `publish.yml` popsané výše publikuje na npm automaticky při verzovacích tagách, s provenance. Protože `yarn twenty app:publish` při běhu v CI přidá `--provenance` a `--access public` za vás, workflow nepotřebuje žádné přepínače npm — pouze jednorázové nastavení důvěryhodného vydavatele.
+
+Pro jiné CI systémy (GitLab CI, CircleCI atd.) spusťte `yarn install` a poté `yarn twenty app:publish`. Provenance se vydává, pokud prostředí umí vytvořit token OIDC, a v opačném případě se automaticky vynechá.
+
+<Note>
+**npm provenance** přidává k vašemu záznamu na npm odznak důvěryhodnosti a umožňuje uživatelům ověřit, že balíček byl sestaven z konkrétního commitu ve veřejné CI pipeline. Také vám umožňuje uplatnit vlastnictví vaší aplikace na tržišti Twenty. Podrobnosti najdete v [dokumentaci k npm provenance](https://docs.npmjs.com/generating-provenance-statements).
+</Note>
+
+## Instalace aplikací
+
+Jakmile je aplikace publikována (npm) nebo nasazena (tarball), mohou ji pracovní prostory nainstalovat prostřednictvím uživatelského rozhraní.
+
+Přejděte na stránku **Nastavení > Aplikace** v Twenty, kde lze procházet a instalovat jak aplikace z tržiště, tak aplikace nasazené jako tarball.
+
+{/* TODO: add screenshot of the UI when the app is registered */}
+
+Aplikace můžete nainstalovat také z příkazového řádku:
+
+```bash filename="Terminal"
+yarn twenty app:install
+```
+
+<Note>
+Server při instalaci vynucuje verzování semver a zrcadlí pravidla pro nasazení:
+
+* Instalace stejné verze, která je již nainstalována ve vašem pracovním prostoru, je odmítnuta s chybou `APP_ALREADY_INSTALLED`.
+* Instalace nižší verze, než je aktuálně nainstalovaná, je odmítnuta s chybou `CANNOT_DOWNGRADE_APPLICATION`.
+
+K instalaci novější verze ji nejprve nasaďte nebo publikujte, poté znovu spusťte `yarn twenty app:install`.
+</Note>

packages/twenty-docs/l/cs/developers/extend/apps/operations/sync-and-recovery.mdx

@@ -0,0 +1,126 @@
+---
+title: Synchronizace a obnovení
+description: Který příkaz kdy použít, jak číst výstup synchronizace a jak postupovat po jednotlivých krocích při obnově v případě odchýlení lokálních metadat — ještě předtím, než sáhnete k úplnému resetu.
+icon: compass
+---
+
+Lokální vývoj aplikací se točí kolem **synchronizace**: CLI znovu sestaví váš manifest a server aplikuje pouze rozdíly mezi ním a metadaty, která už jsou ve vašem pracovním prostoru. Tato stránka popisuje, po kterém příkazu sáhnout, jak číst, co synchronizace změnila, a co dělat — v daném pořadí — když lokální stav vypadá nekonzistentně.
+
+## Jaký příkaz, kdy
+
+<Note>
+Pro každodenní lokální iteraci téměř vždy chcete `yarn twenty dev`. Nasazování a publikování slouží k vydávání verzí, **ne** pro lokální vývojovou smyčku.
+</Note>
+
+| Chcete…                                                   | Příkaz                              | Poznámky                                                                                                              |
+| --------------------------------------------------------- | ----------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
+| Iterujte lokálně s živou synchronizací                    | `yarn twenty dev`                   | Sleduje vaše soubory a při každé změně spustí synchronizaci.                                                          |
+| Jednorázová synchronizace a ukončení (CI, skripty, hooky) | `yarn twenty apply`                 | Provede jedno sestavení + synchronizaci a skončí. Přidejte `--force`, abyste přeskočili potvrzení destruktivní změny. |
+| Náhled změn **bez jejich aplikování**                     | `yarn twenty plan`                  | Spočítá a vypíše rozdíly; nic nezapisuje.                                                                             |
+| Odebrat aplikaci z pracovního prostoru                    | `yarn twenty app:uninstall`         | Přidejte `--yes` pro přeskočení výzvy.                                                                                |
+| Odeslat tarball na server                                 | `yarn twenty app:publish --private` | Vyžaduje **přísně vyšší** verzi v `package.json` — viz [Publikování](/l/cs/developers/extend/apps/operations/publishing).  |
+| Publikovat na marketplace (npm)                           | `yarn twenty app:publish`           | —                                                                                                                     |
+| Nainstalovat / aktualizovat nasazenou verzi               | `yarn twenty app:install`           | Nainstaluje aktuálně nasazenou verzi.                                                                                 |
+| Vymazat lokální server a začít znovu                      | `yarn twenty docker:reset`          | Smaže **všechna** lokální data — krajní řešení.                                                                       |
+
+<Note>
+`yarn twenty dev --once` a `yarn twenty dev --once --dry-run` stále fungují jako zastaralé aliasy pro `yarn twenty apply` a `yarn twenty plan`.
+</Note>
+
+### Lokální synchronizace nevyžaduje zvýšení verze
+
+Pravidlo striktně rostoucí `version` (`VERSION_ALREADY_EXISTS` při nasazení, `APP_ALREADY_INSTALLED` / `CANNOT_DOWNGRADE_APPLICATION` při instalaci) platí pro **`app:publish` / `app:install`** — cestu vydání. `yarn twenty dev` synchronizuje váš manifest na místě a nikdy nevyžaduje změnu verze, takže kvůli iteraci nemusíte sahat na `package.json`. Pokud zvyšujete verzi, abyste otestovali lokální změnu, používáte cestu vydání, i když chcete vývojovou smyčku.
+
+## Čtení výstupu synchronizace
+
+Každá synchronizace vypíše změny metadat, které aplikovala (nebo by aplikovala s `plan`), ve stylu Terraformu — jeden blok na entitu s jejími atributy a poté souhrnný řádek:
+
+```text filename="Terminal"
+  # objectMetadata "rocket" will be created
+  + icon          = "IconRocket"
+  + labelSingular = "Rocket"
+  + ...
+
+  # fieldMetadata "launchedAt" will be updated
+  ~ isNullable = false -> true
+
+Plan: 2 to add, 1 to change, 1 to destroy.
+
+✓ Synced My App (4 files)
+```
+
+To je váš první diagnostický nástroj: přesně ukazuje, které objekty, pole a rozložení se změnily, takže si můžete ověřit, že synchronizace udělala to, co jste očekávali, ještě před kontrolou v UI.
+
+Destruktivní změny (`to destroy`) jsou uvedeny s tím, co odstraňují (např. `objectMetadata "auditNote" — drops the table and all its rows`) a vyžadují interaktivní potvrzení, nebo `--force` ve skriptech.
+
+Když synchronizace selže na jedné entitě, chyba uvede problematickou entitu a její `universalIdentifier`, například:
+
+```text
+Migration action 'create' for 'fieldMetadata' (universalIdentifier: 2020...4337) failed
+```
+
+Tento identifikátor použijte k nalezení entity ve vašem manifestu (a případně v pracovním prostoru) místo hádání, která je v konfliktu.
+
+## Náhled změn (plan)
+
+`yarn twenty plan` sestaví váš manifest, požádá server o migrační plán a vypíše ho — **aniž by cokoli aplikoval**. Je to bezpečný způsob, jak si předem zodpovědět otázku „co by tato synchronizace změnila?“ ještě předtím, než se k ní zavážete.
+
+```bash filename="Terminal"
+yarn twenty plan
+```
+
+```text filename="Terminal"
+Building manifest...
+Computing metadata plan (read-only, nothing will be applied)...
+
+  # fieldMetadata "crewCapacity" will be created
+  + ...
+
+Plan: 1 to add, 1 to change, 0 to destroy.
+
+✓ Plan complete for My App — no changes were applied
+```
+
+Plán:
+
+* **Nic nezapisuje** — žádná migrace metadat, žádná aktualizace záznamu aplikace, žádné změny výchozí role / karty a žádná generace API klienta.
+* Vrací **stejný diff**, jaký by aplikovala skutečná synchronizace, takže můžete předem zkontrolovat vytvořené / aktualizované / smazané entity.
+* Je užitečný před rizikovou změnou, při kontrole změny vygenerované pomocí AI nebo ve skriptu, který má selhat, pokud se má provést neočekávaná změna.
+
+<Note>
+Plán zobrazuje pouze náhled změn **metadat** a vyžaduje, aby byla aplikace alespoň jednou synchronizovaná (aby o ní pracovní prostor věděl). Pokud jej spustíte proti aplikaci, která nikdy nebyla synchronizovaná, server ohlásí, že aplikace není nainstalovaná — nejprve jednou spusťte `yarn twenty dev`.
+</Note>
+
+## Postup obnovy
+
+Když lokální metadata vypadají špatně, postupujte v tomto pořadí a zastavte se, jakmile se problém vyřeší. Každý další krok je rušivější než ten předchozí.
+
+1. **Znovu synchronizujte.** Znovu spusťte `yarn twenty apply`. Synchronizace jsou idempotentní — znovu spuštěný čistý manifest je bezpečný a často vyřeší přechodný problém.
+2. **Prohlédněte si plán.** Spusťte `yarn twenty plan`, abyste přesně viděli, co chce další synchronizace změnit, aniž by to aplikovala.
+3. **Přečtěte si pojmenovanou chybu.** Pokud synchronizace selže, poznamenejte si typ metadat a `universalIdentifier` ve zprávě (viz výše) a tuto entitu najděte ve svém manifestu. Konflikt obvykle ukazuje na duplicitní nebo znovu použitý identifikátor.
+4. **Odinstalujte a znovu nainstalujte.** `yarn twenty app:uninstall`, poté znovu synchronizujte (`yarn twenty dev`). Tím znovu vybudujete metadata aplikace z čistého stavu, zatímco zbytek vašeho pracovního prostoru zůstane nedotčený.
+5. **Úplný reset (krajní řešení).** `yarn twenty docker:reset`, poté znovu naplňte data a synchronizujte.
+
+<Warning>
+`yarn twenty docker:reset` smaže **veškerá** data ve vaší lokální instanci — každý pracovní prostor, záznam i aplikaci. Použijte jej až tehdy, když selžou předchozí kroky.
+</Warning>
+
+<Note>
+Nastala chyba v metadatech? Prosíme, [vytvořte issue](https://github.com/twentyhq/twenty/issues/new/choose) a přiložte chybovou zprávu selhané migrace (s typem metadat a `universalIdentifier`), výstup `Metadata changes` ze synchronizace a příkazy, které jste spustili.
+</Note>
+
+## Vyhněte se souběžným synchronizacím v jednom pracovním prostoru
+
+Synchronizace aplikuje migrace metadat. Spouštění několika synchronizačních, nasazovacích nebo instalačních operací proti **stejnému pracovnímu prostoru ve stejnou dobu** — například z víc terminálů nebo od více AI agentů iterujících paralelně — může tyto migrace prokládat a zanechat metadata v částečně aplikovaném stavu.
+
+Server serializuje synchronizace pro každý pracovní prostor, aby tomu zabránil, ale přesto byste citlivé operace s metadaty měli směrovat přes **jeden jediný** proces místo toho, abyste je spouštěli souběžně. Pokud orchestrujete vývoj s více agenty, směrujte jejich volání sync/deploy/install přes jednu frontu, aby vždy běžel jen jeden proces.
+
+## Rozlišení typů selhání
+
+Když se něco pokazí, diff metadat a pojmenované chyby vám umožní lokalizovat selhání:
+
+* **Chyba sestavení manifestu** — CLI selže ještě před synchronizací (`MANIFEST_BUILD_FAILED`, `TYPECHECK_FAILED`); opravte zdrojový kód své aplikace.
+* **Chyba synchronizace / migrace** — sestavení proběhne úspěšně, ale aplikování diffu selže a uvede entitu a `universalIdentifier`; opravte konfliktní metadata.
+* **Chyba velikosti závislostí** — synchronizace nebo instalace selže, protože produkční `dependencies` aplikace jsou příliš velké na to, aby je bylo možné nainstalovat jako runtime vrstvu (`LOGIC_FUNCTION_DEPENDENCIES_SIZE_EXCEEDED`); přesuňte balíčky, které vaše logické funkce za běhu neimportují (UI knihovny, vývojářské nástroje), do `devDependencies`.
+* **Chyba za běhu aplikačního kódu** — synchronizace proběhne úspěšně, ale vaše logické funkce nebo komponenty se za běhu chovají nesprávně; zkontrolujte [protokoly funkcí](/l/cs/developers/extend/apps/operations/cli).
+* **Lokální stav instance** — neplatí nic z výše uvedeného a pracovní prostor stále vypadá chybně; pokračujte dolů po žebříčku obnovy.

packages/twenty-docs/l/cs/developers/extend/apps/operations/testing.mdx

@@ -0,0 +1,264 @@
+---
+title: Testování
+description: Nastavení Vitestu, integrační testy proti reálnému serveru Twenty, kontrola typů a CI s GitHub Actions.
+icon: flask
+---
+
+SDK poskytuje programová rozhraní, která vám umožní z testovacího kódu aplikaci sestavit, nasadit, nainstalovat a odinstalovat. V kombinaci s [Vitest](https://vitest.dev/) a typovanými klienty API můžete psát integrační testy, které ověří, že vaše aplikace funguje end-to-end proti reálnému serveru Twenty.
+
+## Používání balíčků npm
+
+Ve své aplikaci můžete nainstalovat a používat libovolný balíček npm. Logické funkce i frontendové komponenty se bundlují pomocí [esbuild](https://esbuild.github.io/), který vloží jejich závislosti přímo do výstupu — za běhu nejsou potřeba žádné `node_modules`.
+
+### Instalace balíčku
+
+```bash filename="Terminal"
+yarn add axios
+```
+
+Poté jej importujte ve svém kódu:
+
+```ts src/logic-functions/fetch-data.ts
+import { defineLogicFunction } from 'twenty-sdk/define';
+import axios from 'axios';
+
+const handler = async (): Promise<any> => {
+  const { data } = await axios.get('https://api.example.com/data');
+
+  return { data };
+};
+
+export default defineLogicFunction({
+  universalIdentifier: '...',
+  name: 'fetch-data',
+  description: 'Fetches data from an external API',
+  timeoutSeconds: 10,
+  handler,
+});
+```
+
+Stejně to funguje i pro frontendové komponenty:
+
+```tsx src/front-components/chart.tsx
+import { defineFrontComponent } from 'twenty-sdk/define';
+import { format } from 'date-fns';
+
+const DateWidget = () => {
+  return <p>Today is {format(new Date(), 'MMMM do, yyyy')}</p>;
+};
+
+export default defineFrontComponent({
+  universalIdentifier: '...',
+  name: 'date-widget',
+  component: DateWidget,
+});
+```
+
+### Jak funguje bundlování
+
+Krok sestavení používá esbuild k vytvoření jediného samostatného souboru pro každou logickou funkci a každou frontendovou komponentu. Importované balíčky jsou vloženy přímo do bundlu, s výjimkou těch, které jsou uvedeny níže.
+
+**Logické funkce** běží v prostředí Node.js. Vestavěné moduly Node (`fs`, `path`, `crypto`, `http` atd.) jsou k dispozici a není je třeba instalovat.
+
+**Frontendové komponenty** běží ve Web Workeru. Vestavěné moduly Node nejsou k dispozici — pouze balíčky npm, které fungují v prohlížečovém prostředí. Všimněte si, že sandbox implementuje *částečné* DOM, takže balíček se může bez problémů sestavit, ale přesto selhat za běhu; viz [Aktuální omezení](/l/cs/developers/extend/apps/layout/front-components#current-limitations).
+
+V obou prostředích jsou jako předpřipravené moduly k dispozici `twenty-client-sdk/core` a `twenty-client-sdk/metadata` — nejsou součástí bundlu, ale server je za běhu načítá.
+
+Frontendové komponenty mohou také sdílet závislosti prostřednictvím [balíčku sdílených závislostí](/l/cs/developers/extend/apps/layout/front-components#sharing-dependencies-across-front-components). Balíčky uvedené v poli `frontComponentSharedDependencies` souboru package.json aplikace jsou sestaveny jednou do samostatného souboru a za běhu se načítají z něj, místo aby byly vloženy do každé komponenty. Komponenta, která importuje pouze sdílené balíčky, tak v sobě nese téměř žádný vlastní kód závislostí.
+
+## Nastavení
+
+Vygenerovaná aplikace již obsahuje Vitest. Pokud to nastavujete ručně, nainstalujte závislosti:
+
+```bash filename="Terminal"
+yarn add -D vitest vite-tsconfig-paths
+```
+
+Vytvořte `vitest.config.ts` v kořeni vaší aplikace:
+
+```ts vitest.config.ts
+import tsconfigPaths from 'vite-tsconfig-paths';
+import { defineConfig } from 'vitest/config';
+
+const TWENTY_API_URL = process.env.TWENTY_API_URL ?? 'http://localhost:2020';
+const TWENTY_API_KEY = process.env.TWENTY_API_KEY ?? '<the pre-seeded local dev key>';
+
+// Make env vars available to globalSetup (test.env only applies to workers)
+process.env.TWENTY_API_URL = TWENTY_API_URL;
+process.env.TWENTY_API_KEY = TWENTY_API_KEY;
+
+export default defineConfig({
+  plugins: [
+    tsconfigPaths({
+      projects: ['tsconfig.spec.json'],
+      ignoreConfigErrors: true,
+    }),
+  ],
+  test: {
+    testTimeout: 120_000,
+    hookTimeout: 120_000,
+    fileParallelism: false,
+    include: ['src/**/*.integration-test.ts'],
+    globalSetup: ['src/__tests__/global-setup.ts'],
+    env: {
+      TWENTY_API_URL,
+      TWENTY_API_KEY,
+    },
+  },
+});
+```
+
+Vytvořte globální soubor pro nastavení, který ověří, že je server dosažitelný, zapíše testovací konfiguraci pro SDK (`~/.twenty/config.test.json`) a před spuštěním testů provede synchronizaci aplikace:
+
+```ts src/__tests__/global-setup.ts
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+
+import { appDevOnce, appUninstall } from 'twenty-sdk/cli';
+
+const APP_PATH = process.cwd();
+const CONFIG_DIR = path.join(os.homedir(), '.twenty');
+
+export async function setup() {
+  const apiUrl = process.env.TWENTY_API_URL!;
+  const apiKey = process.env.TWENTY_API_KEY!;
+
+  // Verify the server is running
+  const response = await fetch(`${apiUrl}/healthz`);
+  if (!response.ok) {
+    throw new Error(`Twenty server is not reachable at ${apiUrl}.`);
+  }
+
+  // Write the SDK's test config (the CLI reads config.test.json when NODE_ENV=test)
+  fs.mkdirSync(CONFIG_DIR, { recursive: true });
+  fs.writeFileSync(
+    path.join(CONFIG_DIR, 'config.test.json'),
+    JSON.stringify({
+      remotes: { local: { apiUrl, apiKey } },
+      defaultRemote: 'local',
+    }, null, 2),
+  );
+
+  // Start from a clean slate, then sync the app
+  await appUninstall({ appPath: APP_PATH }).catch(() => {});
+
+  const result = await appDevOnce({ appPath: APP_PATH });
+  if (!result.success) {
+    throw new Error(`Dev sync failed: ${result.error?.message}`);
+  }
+}
+
+export async function teardown() {
+  await appUninstall({ appPath: APP_PATH });
+}
+```
+
+## Programová rozhraní SDK
+
+Subcesta `twenty-sdk/cli` exportuje funkce, které můžete volat přímo z testovacího kódu:
+
+| Funkce         | Popis                                                                          |
+| -------------- | ------------------------------------------------------------------------------ |
+| `appBuild`     | Sestaví aplikaci a volitelně zabalí tarball                                    |
+| `appDeploy`    | Nahraje tarball na server                                                      |
+| `appDevOnce`   | Jednorázově sestaví a synchronizuje aplikaci (stejně jako `yarn twenty apply`) |
+| `appInstall`   | Nainstaluje aplikaci do aktivního pracovního prostoru                          |
+| `appUninstall` | Odinstaluje aplikaci z aktivního pracovního prostoru                           |
+
+Každá funkce vrací objekt výsledku se `success: boolean` a buď `data`, nebo `error`.
+
+## Psání integračního testu
+
+Zde je kompletní příklad, který aplikaci sestaví, nasadí a nainstaluje a poté ověří, že se objeví v pracovním prostoru:
+
+```ts src/__tests__/app-install.integration-test.ts
+import { APPLICATION_UNIVERSAL_IDENTIFIER } from 'src/application-config';
+import { appBuild, appDeploy, appInstall, appUninstall } from 'twenty-sdk/cli';
+import { MetadataApiClient } from 'twenty-client-sdk/metadata';
+import { afterAll, beforeAll, describe, expect, it } from 'vitest';
+
+const APP_PATH = process.cwd();
+
+describe('App installation', () => {
+  beforeAll(async () => {
+    const buildResult = await appBuild({
+      appPath: APP_PATH,
+      tarball: true,
+      onProgress: (message: string) => console.log(`[build] ${message}`),
+    });
+
+    if (!buildResult.success) {
+      throw new Error(`Build failed: ${buildResult.error?.message}`);
+    }
+
+    const deployResult = await appDeploy({
+      tarballPath: buildResult.data.tarballPath!,
+      onProgress: (message: string) => console.log(`[deploy] ${message}`),
+    });
+
+    if (!deployResult.success) {
+      throw new Error(`Deploy failed: ${deployResult.error?.message}`);
+    }
+
+    const installResult = await appInstall({ appPath: APP_PATH });
+
+    if (!installResult.success) {
+      throw new Error(`Install failed: ${installResult.error?.message}`);
+    }
+  });
+
+  afterAll(async () => {
+    await appUninstall({ appPath: APP_PATH });
+  });
+
+  it('should find the installed app in the workspace', async () => {
+    const metadataClient = new MetadataApiClient();
+
+    const result = await metadataClient.query({
+      findManyApplications: {
+        id: true,
+        name: true,
+        universalIdentifier: true,
+      },
+    });
+
+    const installedApp = result.findManyApplications.find(
+      (app: { universalIdentifier: string }) =>
+        app.universalIdentifier === APPLICATION_UNIVERSAL_IDENTIFIER,
+    );
+
+    expect(installedApp).toBeDefined();
+  });
+});
+```
+
+## Spuštění testů
+
+Ujistěte se, že běží váš lokální server Twenty, a poté:
+
+```bash filename="Terminal"
+yarn test
+```
+
+Nebo v režimu watch během vývoje:
+
+```bash filename="Terminal"
+yarn test:watch
+```
+
+## Kontrola typů
+
+Kontrolu typů můžete spustit i na vaší aplikaci bez spuštění testů:
+
+```bash filename="Terminal"
+yarn twenty dev:typecheck
+```
+
+Spustí se `tsc --noEmit` proti souboru `tsconfig.json` vaší aplikace a nahlásí se případné chyby typů. Vygenerované aplikace také obsahují skript `yarn typecheck`, který pokrývá i testovací soubory (`tsconfig.spec.json`).
+
+## CI s GitHub Actions
+
+Generátor kostry vytvoří připravený k použití workflow v `.github/workflows/ci.yml`. Při každém pushi do `main` a při každém pull requestu spustí efemérní server Twenty v runneru (pomocí akce `twentyhq/twenty/.github/actions/spawn-twenty-app-dev-test`), poté spustí `yarn lint`, `yarn typecheck`, `yarn test:unit` a `yarn test` s `TWENTY_API_URL` / `TWENTY_API_KEY` směřujícími na tento server. Nejsou vyžadovány žádné tajné údaje a verzi serveru můžete připnout pomocí proměnné prostředí `TWENTY_VERSION` na začátku workflow.
+
+Úplný postup pro tři workflow generované kostrou (`ci.yml`, nasazovací pipeline `cd.yml` a `publish.yml` pro publikování na npm) najdete v části [Publishing → Automated CI/CD](/l/cs/developers/extend/apps/operations/publishing#automated-cicd-scaffolded-workflows).

packages/twenty-docs/l/cs/developers/extend/apps/operations/translations.mdx

@@ -0,0 +1,136 @@
+---
+title: Překlady
+description: Doručte svou aplikaci v několika jazycích — překládejte popisky manifestu a texty uživatelského rozhraní prostřednictvím jednoho katalogu locales.
+icon: language
+---
+
+Aplikace Twenty jsou psané v **angličtině**: řetězce ve vašem zdrojovém kódu a manifestu tvoří anglický zdrojový text, `en` je zdrojová locale, ze které překládáte, a jakákoli locale ponechaná bez překladu se na ni automaticky vrátí.
+
+Vaše aplikace má dva druhy přeložitelného textu a oba procházejí stejným
+katalogem `locales/`:
+
+* **Popisky manifestu** — názvy objektů a polí, názvy zobrazení, položky nabídky a
+  další řetězce deklarované v metadatech vaší aplikace.
+* **Řetězce front komponent** — text uživatelského rozhraní, který vykreslují vaše React front komponenty.
+
+Označíte přeložitelné řetězce, extrahujete je do katalogů pro jednotlivé jazyky,
+přeložíte tyto katalogy a build doručí správný jazyk pro
+aktuálního uživatele — bez dalšího zapojování.
+
+## Označování řetězců front komponent
+
+Importujte pomocné překladové funkce z `twenty-sdk/front-component`:
+
+```tsx
+import { Trans, t, msg, useTranslate } from 'twenty-sdk/front-component';
+
+const STATUSES = [
+  { id: 'draft', label: msg('Draft') },
+  { id: 'sent', label: msg('Sent') },
+];
+
+const Card = ({ count, name }: { count: number; name: string }) => {
+  const { t } = useTranslate();
+
+  return (
+    <section>
+      {/* Static text — reactive to the user's locale */}
+      <Trans>Loading postcard…</Trans>
+
+      {/* Disambiguate identical sources with a context */}
+      <Trans context="card-title">Untitled</Trans>
+
+      {/* Interpolation: pass values explicitly */}
+      <p>{t('Hi {name}', { name })}</p>
+      <p>{t('Saved {count} cards', { count })}</p>
+
+      {/* Resolve a lazily-declared descriptor */}
+      <ul>{STATUSES.map((s) => <li key={s.id}>{t(s.label)}</li>)}</ul>
+    </section>
+  );
+};
+```
+
+### Kdy co použít
+
+* **`Trans`** — statický text v JSX. Použijte props `message` a `values` pro
+  interpolaci, jak je ukázáno v `Trans message="Hi {name}" values={{ name }}`;
+  interpolace přímo v potomcích není staticky extrahovatelná.
+* **`useTranslate().t`** — dynamické řetězce uvnitř komponenty. Znovu se vykreslí, když
+  uživatel přepne jazyk. Uvnitř renderu tomuto dávejte přednost.
+* **`t(...)`** (importované přímo) — okamžitý překlad použitelný **kdekoli**,
+  včetně obsluh událostí, pomocných funkcí a v modulovém rozsahu — nejen uvnitř renderu.
+* **`msg(...)`** — líný deskriptor pro řetězce deklarované jako data (konstanty,
+  konfigurace). Vyhodnoťte jej později pomocí `t(descriptor)`.
+
+### Kontext
+
+Předejte `context`, abyste odlišili identické zdrojové řetězce, které se překládají
+rozdílně:
+
+```tsx
+t({ message: 'Open', context: 'door' });
+t({ message: 'Open', context: 'window' });
+<Trans context="card-title">Untitled</Trans>
+```
+
+Kontextové řetězce se v jazykových katalozích objevují jako skupina s klíčem podle svého kontextu: `"\<context>": { "\<message>": "\<translation>" }`. Štítky manifestu jsou kontextové již svou konstrukcí — každý z nich nese roli metadat, kterou plní (`objectMetadata.labelSingular`, `fieldMetadata.label`, `view.name`, …), takže stejné slovo se může přeložit odlišně jako název objektu a jako název zobrazení.
+
+## Extrahování a překládání
+
+Spusťte příkaz pro extrakci z adresáře své aplikace:
+
+```bash
+twenty dev:translations-extract                  # collect strings into locales/en.json
+twenty dev:translations-extract --locale fr-FR   # also scaffold a target locale
+```
+
+Extrakce shromáždí jak popisky manifestu, tak řetězce `t()`/`msg()`/`Trans`
+z vašeho zdrojového kódu front komponent do `locales/\<locale>.json`, kde jsou klíčem
+zdrojové řetězce. Doplňte překlady:
+
+```json
+// locales/fr-FR.json
+{
+  "Loading postcard…": "Chargement de la carte…",
+  "Hi {name}": "Bonjour {name}",
+  "Saved {count} cards": "{count} cartes enregistrées",
+  "door": {
+    "Open": "Ouvrir"
+  },
+  "objectMetadata.labelSingular": {
+    "Postcard": "Carte postale"
+  }
+}
+```
+
+Řetězce bez kontextu jsou ploché položky; kontextové řetězce — včetně každého štítku manifestu — jsou vnořené pod svým kontextovým klíčem.
+
+Zástupné symboly jako `{name}` jsou nahrazeny za běhu — ponechejte je v
+překladu. Jakýkoli řetězec ponechaný prázdný spadne zpět na zdrojový text.
+
+## Jak to běží
+
+`twenty dev:build` zkompiluje katalogy a doručí správný jazyk pro
+aktuálního uživatele: popisky manifestu jsou vyhodnoceny na straně serveru a katalogy
+front komponent jsou zabudovány do každého balíčku komponent. Za běhu komponenta čte
+jazykovou verzi (locale) z vykonávacího kontextu (aktuální jazyk hostitele) a překládá
+každý řetězec podle svého katalogu, přičemž při chybějícím překladu spadne zpět na zdroj. Přepnutí jazyka v hostiteli znovu vykreslí řetězce `Trans` a
+`useTranslate().t` v reálném čase.
+
+Popisky manifestu se kompilují při každé synchronizaci — stejně při `twenty dev:build`, `twenty apply`
+jako při průběžném sledování pomocí `twenty dev` — takže pro zobrazení nového textu stačí upravit soubor lokalizace a
+provést synchronizaci. Katalogy komponent Front se při sestavení začleňují do
+každého balíčku komponent, takže změna některého z nich stále znamená
+znovu spustit `twenty dev:build` (a znovu nasadit).
+
+Textoví potomci `Trans` mohou být na více řádcích — bílé znaky se slučují
+stejně jako je slučuje JSX, takže oba tyto případy se extrahují pod klíčem `Welcome back`:
+
+```tsx
+<Trans>Welcome back</Trans>
+<Trans>
+  Welcome
+  back
+</Trans>
+```