i18n - docs translations (#18534)

Created by Github action --------- Co-authored-by: github-actions <github-actions@twenty.com> Co-authored-by: Charles Bochet <charles@twenty.com>
2026-03-10 15:57:15 +01:00
parent d1c95e380e
commit 982f0c4a4d
87 changed files with 9331 additions and 280 deletions
@@ -0,0 +1,233 @@
+---
+title: Primeiros passos
+description: Crie seu primeiro app do Twenty em minutos.
+---
+
+<Warning>
+Os aplicativos estão atualmente em testes alfa. O recurso é funcional, mas ainda está evoluindo.
+</Warning>
+
+Os apps permitem que você estenda o Twenty com objetos, campos, funções de lógica, habilidades de IA e componentes de UI personalizados — tudo gerenciado como código.
+
+**O que você pode fazer hoje:**
+
+* Defina objetos e campos personalizados como código (modelo de dados gerenciado)
+* Crie funções de lógica com gatilhos personalizados (rotas HTTP, cron, eventos de banco de dados)
+* Defina habilidades para agentes de IA
+* Crie componentes de front-end que renderizam dentro da UI do Twenty
+* Implemente o mesmo aplicativo em vários espaços de trabalho
+
+## Pré-requisitos
+
+* Node.js 24+ e Yarn 4
+* Um espaço de trabalho do Twenty e uma chave de API (crie uma em https://app.twenty.com/settings/api-webhooks)
+
+## Primeiros passos
+
+Crie um novo aplicativo usando o gerador oficial, depois autentique-se e comece a desenvolver:
+
+```bash filename="Terminal"
+# Scaffold a new app (includes all examples by default)
+npx create-twenty-app@latest my-twenty-app
+cd my-twenty-app
+
+# Start dev mode: automatically syncs local changes to your workspace
+yarn twenty app:dev
+```
+
+O gerador de estrutura oferece suporte a dois modos para controlar quais arquivos de exemplo são incluídos:
+
+```bash filename="Terminal"
+# Default (exhaustive): all examples (object, field, logic function, front component, view, navigation menu item, skill)
+npx create-twenty-app@latest my-app
+
+# Minimal: only core files (application-config.ts and default-role.ts)
+npx create-twenty-app@latest my-app --minimal
+```
+
+A partir daqui você pode:
+
+```bash filename="Terminal"
+# Add a new entity to your application (guided)
+yarn twenty entity:add
+
+# Watch your application's function logs
+yarn twenty function:logs
+
+# Execute a function by name
+yarn twenty function:execute -n my-function -p '{"name": "test"}'
+
+# Execute the pre-install function
+yarn twenty function:execute --preInstall
+
+# Execute the post-install function
+yarn twenty function:execute --postInstall
+
+# Uninstall the application from the current workspace
+yarn twenty app:uninstall
+
+# Display commands' help
+yarn twenty help
+```
+
+Veja também: as páginas de referência da CLI para [create-twenty-app](https://www.npmjs.com/package/create-twenty-app) e [twenty-sdk CLI](https://www.npmjs.com/package/twenty-sdk).
+
+## Estrutura do projeto (com scaffold)
+
+Ao executar `npx create-twenty-app@latest my-twenty-app`, o gerador:
+
+* Copia um aplicativo base mínimo para `my-twenty-app/`
+* Adiciona uma dependência local `twenty-sdk` e a configuração do Yarn 4
+* Cria arquivos de configuração e scripts conectados à CLI `twenty`
+* Gera arquivos principais (configuração da aplicação, papel padrão para funções de lógica, funções de pré-instalação e pós-instalação) além de arquivos de exemplo com base no modo de geração de estrutura
+
+Um app recém-criado com o modo padrão `--exhaustive` fica assim:
+
+```text filename="my-twenty-app/"
+my-twenty-app/
+  package.json
+  yarn.lock
+  .gitignore
+  .nvmrc
+  .yarnrc.yml
+  .yarn/
+    install-state.gz
+  .oxlintrc.json
+  tsconfig.json
+  README.md
+  public/                           # Public assets folder (images, fonts, etc.)
+  src/
+  ├── application-config.ts           # Required - main application configuration
+  ├── roles/
+  │   └── default-role.ts               # Default role for logic functions
+  ├── objects/
+  │   └── example-object.ts             # Example custom object definition
+  ├── fields/
+  │   └── example-field.ts              # Example standalone field definition
+  ├── logic-functions/
+  │   ├── hello-world.ts                # Example logic function
+  │   ├── pre-install.ts                # Pre-install logic function
+  │   └── post-install.ts               # Post-install logic function
+  ├── front-components/
+  │   └── hello-world.tsx               # Example front component
+  ├── views/
+  │   └── example-view.ts                # Example saved view definition
+  ├── navigation-menu-items/
+  │   └── example-navigation-menu-item.ts # Example sidebar navigation link
+  └── skills/
+      └── example-skill.ts                # Example AI agent skill definition
+```
+
+Com `--minimal`, apenas os arquivos principais são criados (`application-config.ts`, `roles/default-role.ts`, `logic-functions/pre-install.ts` e `logic-functions/post-install.ts`).
+
+Em alto nível:
+
+* **package.json**: Declara o nome do app, versão, engines (Node 24+, Yarn 4), e adiciona `twenty-sdk` além de um script `twenty` que delega para a CLI `twenty` local. Execute `yarn twenty help` para listar todos os comandos disponíveis.
+* **.gitignore**: Ignora artefatos comuns como `node_modules`, `.yarn`, `generated/` (cliente tipado), `dist/`, `build/`, pastas de cobertura, arquivos de log e arquivos `.env*`.
+* **yarn.lock**, **.yarnrc.yml**, **.yarn/**: Bloqueiam e configuram a ferramenta Yarn 4 usada pelo projeto.
+* **.nvmrc**: Fixa a versão do Node.js esperada pelo projeto.
+* **.oxlintrc.json** e **tsconfig.json**: Fornecem lint e configuração do TypeScript para os fontes TypeScript do seu aplicativo.
+* **README.md**: Um README curto na raiz do aplicativo com instruções básicas.
+* **public/**: Uma pasta para armazenar recursos públicos (imagens, fontes, arquivos estáticos) que serão servidos com sua aplicação. Os arquivos colocados aqui são enviados durante a sincronização e ficam acessíveis em tempo de execução.
+* **src/**: O local principal onde você define seu aplicativo como código
+
+### Detecção de entidades
+
+O SDK detecta entidades analisando seus arquivos TypeScript em busca de chamadas **`export default define<Entity>({...})`**. Cada tipo de entidade tem uma função utilitária correspondente exportada de `twenty-sdk`:
+
+| Função utilitária                | Tipo de entidade                                                     |
+| -------------------------------- | -------------------------------------------------------------------- |
+| `defineObject`                   | Definições de objetos personalizados                                 |
+| `defineLogicFunction`            | Definições de funções de lógica                                      |
+| `definePreInstallLogicFunction`  | Função de lógica de pré-instalação (é executada antes da instalação) |
+| `definePostInstallLogicFunction` | Função de lógica de pós-instalação (é executada após a instalação)   |
+| `defineFrontComponent`           | Definições de componentes de front-end                               |
+| `defineRole`                     | Definições de papéis                                                 |
+| `defineField`                    | Extensões de campos para objetos existentes                          |
+| `defineView`                     | Definições de visualizações salvas                                   |
+| `defineNavigationMenuItem`       | Definições de itens do menu de navegação                             |
+| `defineSkill`                    | Definições de habilidades de agente de IA                            |
+
+<Note>
+**A nomeação de arquivos é flexível.** A detecção de entidades é baseada em AST — o SDK varre seus arquivos fonte em busca do padrão `export default define<Entity>({...})`. Você pode organizar seus arquivos e pastas como quiser. Agrupar por tipo de entidade (por exemplo, `logic-functions/`, `roles/`) é apenas uma convenção para organização do código, não um requisito.
+</Note>
+
+Exemplo de uma entidade detectada:
+
+```typescript
+// This file can be named anything and placed anywhere in src/
+import { defineObject, FieldType } from 'twenty-sdk';
+
+export default defineObject({
+  universalIdentifier: '...',
+  nameSingular: 'postCard',
+  // ... rest of config
+});
+```
+
+Comandos posteriores adicionarão mais arquivos e pastas:
+
+* `yarn twenty app:dev` irá gerar automaticamente dois clientes de API tipados em `node_modules/twenty-sdk/generated`: `CoreApiClient` (para dados do espaço de trabalho via `/graphql`) e `MetadataApiClient` (para configuração do espaço de trabalho e envio de arquivos via `/metadata`).
+* `yarn twenty entity:add` adicionará arquivos de definição de entidade em `src/` para seus objetos, funções, componentes de front-end, papéis e habilidades personalizados, entre outros.
+
+## Autenticação
+
+Na primeira vez que você executar `yarn twenty auth:login`, será solicitado o seguinte:
+
+* URL da API (padrão: http://localhost:3000 ou o perfil do seu espaço de trabalho atual)
+* Chave de API
+
+Suas credenciais são armazenadas por usuário em `~/.twenty/config.json`. Você pode manter vários perfis e alternar entre eles.
+
+### Gerenciando espaços de trabalho
+
+```bash filename="Terminal"
+# Login interactively (recommended)
+yarn twenty auth:login
+
+# Login to a specific workspace profile
+yarn twenty auth:login --workspace my-custom-workspace
+
+# List all configured workspaces
+yarn twenty auth:list
+
+# Switch the default workspace (interactive)
+yarn twenty auth:switch
+
+# Switch to a specific workspace
+yarn twenty auth:switch production
+
+# Check current authentication status
+yarn twenty auth:status
+```
+
+Depois que você alternar os espaços de trabalho com `yarn twenty auth:switch`, todos os comandos subsequentes usarão esse espaço de trabalho por padrão. Você ainda pode substituí-lo temporariamente com `--workspace <name>`.
+
+## Configuração manual (sem o gerador)
+
+Embora recomendemos usar `create-twenty-app` para a melhor experiência inicial, você também pode configurar um projeto manualmente. Não instale a CLI globalmente. Em vez disso, adicione `twenty-sdk` como uma dependência local e configure um único script no seu package.json:
+
+```bash filename="Terminal"
+yarn add -D twenty-sdk
+```
+
+Em seguida, adicione um script `twenty`:
+
+```json filename="package.json"
+{
+  "scripts": {
+    "twenty": "twenty"
+  }
+}
+```
+
+Agora você pode executar todos os comandos via `yarn twenty <command>`, por exemplo, `yarn twenty app:dev`, `yarn twenty help`, etc.
+
+## Resolução de Problemas
+
+* Erros de autenticação: execute `yarn twenty auth:login` e certifique-se de que sua chave de API tenha as permissões necessárias.
+* Não é possível conectar ao servidor: verifique a URL da API e se o servidor do Twenty está acessível.
+* Tipos ou cliente ausentes/desatualizados: reinicie `yarn twenty app:dev` — ele gera automaticamente o cliente tipado.
+* Modo de desenvolvimento não sincronizando: certifique-se de que `yarn twenty app:dev` esteja em execução e de que as alterações não estejam sendo ignoradas pelo seu ambiente.
+
+Canal de ajuda no Discord: https://discord.com/channels/1130383047699738754/1130386664812982322