> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dkscripts.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Utilitários & Locale

> Funções utilitárias compartilhadas e sistema de tradução

# 🛠️ Utilitários & Locale

Esta página documenta as funções utilitárias compartilhadas e o sistema de localização (traduções).

***

## 📦 Utilitários (`utils.lua`)

Funções compartilhadas entre client e server. Localizadas em `config/shared/utils.lua`.

### Notification

Exibe uma notificação para o jogador.

```lua theme={null}
function Notification(...)
    DkNotify(...)
end
```

**Uso Client:**

```lua theme={null}
Notification("red", "Você não tem permissão!")
Notification("green", "Corrida iniciada!", 5000)
```

**Uso Server:**

```lua theme={null}
Notification(source, "red", "Você não tem permissão!")
Notification(source, "yellow", "Alerta!", 7000)
```

**Parâmetros:**

| # | Parâmetro        | Tipo              | Descrição                             |
| - | ---------------- | ----------------- | ------------------------------------- |
| 1 | color/source     | `string`/`number` | Cor (client) ou source (server)       |
| 2 | message/color    | `string`          | Mensagem (client) ou cor (server)     |
| 3 | duration/message | `number`/`string` | Duração (client) ou mensagem (server) |
| 4 | - / duration     | - / `number`      | - / Duração (server)                  |

**Cores disponíveis:**

* `"red"` - Erro
* `"green"` - Sucesso
* `"yellow"` - Alerta
* `"blue"` - Informação

***

### Request

Exibe uma caixa de confirmação para o jogador.

```lua theme={null}
function Request(...)
    return DkRequest(...)
end
```

**Retorno:** `boolean` - Resposta do jogador

**Exemplo:**

```lua theme={null}
local accepted = Request(source, "Deseja iniciar a corrida?")
if accepted then
    -- Iniciar corrida
end
```

***

### Hint

Exibe uma dica temporária na tela.

```lua theme={null}
function Hint(...)
    DkHint(...)
end
```

***

### TimestampConvert

Converte timestamp de milissegundos para segundos.

```lua theme={null}
function TimestampConvert(time)
    return ParseInt(time / 1000)
end
```

**Uso:**

```lua theme={null}
local seconds = TimestampConvert(10000) -- Retorna 10
```

***

### GetItemByIndex

Obtém um item coletável pelo seu identificador.

```lua theme={null}
function GetItemByIndex(index)
    for _, item in pairs(Config.CollectableItems.List) do
        if item.index == index then
            return item
        end
    end
    return nil
end
```

**Exemplo:**

```lua theme={null}
local nitro = GetItemByIndex("nitro")
if nitro then
    print(nitro.name) -- Nome do item
    print(nitro.duration) -- Duração em ms
end
```

***

## 🌐 Sistema de Localização

O sistema de traduções está em `config/shared/locale/`.

### Estrutura de Arquivos

```
locale/
├── !locale.lua    # Carregador principal
├── en.lua         # Inglês
└── ptbr.lua       # Português Brasil
```

### Usando Traduções

```lua theme={null}
local text = Locale("chave_da_traducao")

-- Com parâmetros
local text = Locale("in_cooldown", {30}) -- "Aguarde 30 segundos..."
```

***

## 🇧🇷 Traduções Disponíveis (ptbr)

### Categoria: game

Textos relacionados ao gameplay.

<Tabs>
  <Tab title="Cooldown" icon="clock">
    ```lua theme={null}
    ["in_cooldown"] = "Aguarde <strong>%s segundos</strong> antes de fazer isto novamente."
    ```

    **Uso:** `Locale("in_cooldown", {30})`
  </Tab>

  <Tab title="Nickname" icon="user">
    ```lua theme={null}
    ["nickname_in_use"] = "Este apelido já está em uso, por favor escolha outro."
    ["nickname_invalid"] = "Apelido inválido. Deve conter entre 3 e 20 caracteres."
    ["nickname_error"] = "Ocorreu um erro ao registrar o apelido."
    ["nickname_registered"] = "Apelido registrado com sucesso."
    ["nickname_already_selected"] = "Você já selecionou um apelido."
    ["nickname_missing"] = "Você precisa registrar um apelido para participar das corridas."
    ```
  </Tab>

  <Tab title="Corridas" icon="flag-checkered">
    ```lua theme={null}
    ["race_enter_text"] = "~r~E~w~ - CORRIDA"
    ["race_default_name"] = "Corrida #%d"
    ["race_no_vehicle"] = "Você precisa estar em um veículo para participar da corrida."
    ["race_queue_full"] = "A fila da corrida está cheia no momento. Tente novamente mais tarde."
    ["race_already_in_race"] = "Você já está participando de uma corrida."
    ["race_not_available"] = "A corrida não está disponível no momento."
    ["race_single_already_in_race"] = "Já existe uma corrida em andamento no momento."
    ["race_needed_item_missing"] = "Você não possui o item necessário para participar desta corrida."
    ["race_vehicle_not_allowed"] = "O veículo que você está usando não é permitido nesta corrida."
    ["race_canceled_min_runners_notification"] = "A corrida foi cancelada por não ter corredores suficientes. Mínimo necessário: %d."
    ```
  </Tab>

  <Tab title="Power-ups" icon="gem">
    ```lua theme={null}
    ["collectable_item_name_nitro"] = "Nitro"
    ["collectable_item_name_repair"] = "Reparo"
    ["collectable_item_name_speed_boost"] = "Impulso de Velocidade"
    ["collectable_item_name_shield"] = "Escudo"
    ["collectable_item_name_ghost"] = "Fantasma"

    ["race_collectable_item_won"] = "Você ganhou um item coletável: <strong>%s</strong>."
    ["race_collectable_item_not_found"] = "ERRO: Item coletável não encontrado."
    ["race_collectable_item_not_owned"] = "Você não possui este item coletável."
    ```
  </Tab>

  <Tab title="Polícia" icon="siren">
    ```lua theme={null}
    ["police_alert_race_started"] = "<strong>Corrida ilegal</strong>: Uma corrida foi iniciada em <strong>%s</strong>."
    ["police_last_racer_position"] = "CORREDOR | Última posição coletada"
    ```
  </Tab>

  <Tab title="Webhooks" icon="discord">
    ```lua theme={null}
    ["webhooks_race_started_title"] = "Corrida Iniciada 🚦"
    ["webhooks_race_started_description"] = "Uma nova corrida foi iniciada!"
    ["webhooks_race_finished_title"] = "Corrida Finalizada 🏁"
    ["webhooks_race_finished_description"] = "Uma corrida foi finalizada!"
    ["webhooks_race_racename_field"] = "Nome da Corrida"
    ["webhooks_race_raceid_field"] = "ID da Corrida"
    ["webhooks_race_routeid_field"] = "ID da Rota"
    ["webhooks_race_status_field"] = "Status"
    ["webhooks_race_playerposition_field"] = "Posição do Jogador"
    ["webhooks_race_racelocation_field"] = "Local de Início"
    ["webhooks_race_playerdata_field"] = "Dados do Jogador"
    ["webhooks_race_players_field"] = "Jogadores"
    ```
  </Tab>
</Tabs>

### Categoria: ui

Textos da interface do usuário.

<AccordionGroup>
  <Accordion title="Botões e Ações" icon="hand-pointer" defaultOpen>
    ```lua theme={null}
    ["add"] = "Adicionar"
    ["delete"] = "Excluir"
    ["save"] = "Salvar"
    ["discart"] = "Descartar"
    ["yes"] = "Sim"
    ["no"] = "Não"
    ["none"] = "Nenhuma"
    ["go"] = "JÁ"
    ["enter"] = "ENTRAR"
    ["notify_me"] = "AVISE-ME"
    ["close"] = "Fechar"
    ["configure"] = "Configurar"
    ```
  </Accordion>

  <Accordion title="Painel Principal" icon="window-restore">
    ```lua theme={null}
    ["admin_panel_title"] = "Painel de Administração"
    ["race_panel_title"] = "Painel da Corrida %s"

    ["panel_aside_general"] = "GERAL"
    ["panel_aside_management"] = "GERENCIAMENTO"
    ["panel_aside_options"] = "OPÇÕES"
    ```
  </Accordion>

  <Accordion title="Opções do Menu" icon="list">
    ```lua theme={null}
    ["panel_option_race_management"] = "Gerenciar corridas"
    ["panel_option_settings"] = "Configurações"
    ["panel_option_race_main"] = "Corrida"
    ["panel_option_race_rankings"] = "Ranking"
    ["panel_option_routes_creation"] = "Criação de Rotas"
    ["panel_option_routes_management"] = "Gerenciamento de Rotas"
    ["panel_option_routes_statistics"] = "Estatísticas"
    ```
  </Accordion>

  <Accordion title="Descrições" icon="align-left">
    ```lua theme={null}
    ["description_race_management"] = "Crie novas corridas ou gerencie as existentes."
    ["description_settings"] = "Ajuste suas configurações gerais ou de corrida."
    ["description_race_main"] = "Entre na fila, veja detalhes ou inicie uma corrida."
    ["description_race_rankings"] = "Os recordes de cada rota aparecem aqui..."
    ["description_routes_creation"] = "Crie e visualize rotas de corrida..."
    ["description_routes_management"] = "Gerencie as rotas de corrida existentes..."
    ["description_routes_statistics"] = "Veja estatísticas detalhadas..."
    ```
  </Accordion>

  <Accordion title="Configuração de Corrida" icon="sliders">
    ```lua theme={null}
    ["race_queue_blips"] = "Pontos da fila"
    ["race_prize_bonus"] = "Bônus de premiação"
    ["race_start_blip"] = "Blip de início"
    ["race_needed_item_name"] = "Item necessário (vazio p/ sem item)"
    ["race_needed_item_quantity"] = "Quantidade necessária"
    ["race_cooldown"] = "Cooldown (segundos)"
    ["race_collectable_items"] = "Itens coletáveis"
    ["race_min_racers"] = "Mínimo de corredores"
    ["race_active"] = "Ativada"
    ```
  </Accordion>

  <Accordion title="Veículos Permitidos" icon="car">
    ```lua theme={null}
    ["race_allowed_vehicles"] = "Veículos"
    ["race_allowed_vehicles_option_cars"] = "Carros"
    ["race_allowed_vehicles_option_trucks"] = "Caminhões"
    ["race_allowed_vehicles_option_motorcycles"] = "Motos"
    ```
  </Accordion>
</AccordionGroup>

***

## ➕ Adicionando Novo Idioma

Para adicionar um novo idioma:

<Steps>
  <Step title="Crie o arquivo">
    Crie um novo arquivo em `config/shared/locale/`, por exemplo `es.lua` para espanhol.
  </Step>

  <Step title="Copie a estrutura">
    Copie todo o conteúdo de `ptbr.lua` ou `en.lua`.
  </Step>

  <Step title="Traduza">
    Traduza todas as strings mantendo as chaves originais.
  </Step>

  <Step title="Configure">
    Altere o idioma padrão no arquivo de configuração do script.
  </Step>
</Steps>

**Exemplo:**

```lua theme={null}
-- config/shared/locale/es.lua
Locales["es"] = {
    ["game"] = {
        ["in_cooldown"] = "Espera <strong>%s segundos</strong> antes de hacer esto de nuevo.",
        ["race_no_vehicle"] = "Necesitas estar en un vehículo para participar en la carrera.",
        -- ... outras traduções
    },
    ["ui"] = {
        ["add"] = "Agregar",
        ["delete"] = "Eliminar",
        -- ... outras traduções
    }
}
```

***

## 🔤 Formatação de Strings

### Parâmetros Posicionais

Use `%s` para inserir valores:

```lua theme={null}
["message"] = "Olá, %s!"
-- Uso: Locale("message", {"Mundo"}) -> "Olá, Mundo!"
```

### Múltiplos Parâmetros

```lua theme={null}
["race_info"] = "Corrida %s iniciada com %s jogadores"
-- Uso: Locale("race_info", {"Sprint", 5}) -> "Corrida Sprint iniciada com 5 jogadores"
```

### HTML/Formatação

O sistema suporta tags HTML para estilização:

```lua theme={null}
["important"] = "Isto é <strong>muito importante</strong>!"
["colored"] = "Texto em <span class='font-blue'>azul</span>"
```

<Tip>
  Use `<strong>` para destacar partes importantes da mensagem. A interface renderiza HTML automaticamente.
</Tip>