---
title: "Global Configuration"
description: "Set the translation backend, credentials, and project-wide defaults in config.php – applies to every view button and section."
canonical_url: "https://kirby.tools/docs/content-translator/configuration/global"
---

# Global Configuration

> Set the translation backend, credentials, and project-wide defaults in config.php – applies to every view button and section.

## Translation Provider

At least one translation provider must be configured. Pick a backend below – the [`strategy` option](#strategy) selects which one runs.

<card-group>
<card icon="i-simple-icons-deepl" title="DeepL" to="/docs/content-translator/providers/deepl">

Industry-leading machine translation with a free tier available.

</card>

<card icon="i-ri-sparkling-line" title="AI Translation" to="/docs/content-translator/providers/ai-translation">

Context-aware translation via the [Kirby Copilot](/copilot) plugin (OpenAI, Anthropic, Google, Mistral).

</card>

<card icon="i-ri-puzzle-line" title="Custom Strategy" to="/docs/content-translator/providers/custom-translator">

Plug in any translation API via a closure or a custom `Strategy` implementation.

</card>
</card-group>

## Available Properties

Set global defaults that apply to both **view buttons** and **sections**. These can be overridden in individual blueprints. The following configuration sets DeepL as the translation provider and defines global defaults for field types, title translation, slug translation, confirmation dialogs, and KirbyTags translation:

```php [config.php]
return [
    'johannschopplich.content-translator' => [
        // Translation provider
        'DeepL' => [
            'apiKey' => env('DEEPL_API_KEY')
        ],

        // Global default properties for view buttons and sections
        'fieldTypes' => [
            'blocks',
            'text',
            'textarea'
        ],
        'title' => true,
        'slug' => true,
        'kirbyTags' => [
            'link' => ['text', 'title'],
            'image' => ['alt', 'caption'],
            'file' => ['text', 'title']
        ]
    ]
];
```

`import`, `importFrom`, `batch`, `title`, `slug`, `confirm`, `fieldTypes`, `includeFields`, `excludeFields`, and `kirbyTags` can be set here as project-wide defaults; all of them are described on the [View Button & Section Configuration](/docs/content-translator/configuration/local#available-properties) page. Two blueprint properties have no global counterpart: `systemPrompt` becomes [`ai.systemPrompt`](#aisystemprompt), and `label` falls back to a [Panel translation](/docs/content-translator/configuration/local#localization) rather than a config value. Everything below exists only globally.

### `strategy` <u-badge className="align-middle,ml-2,rounded-full!" label="Mixed" variant="subtle"></u-badge>

Selects the translation backend explicitly. Accepts a string preset, a closure, or a [`Strategy`](/docs/content-translator/php-classes/strategies) instance. Without this option the plugin uses the deprecated `translateFn` if one is configured, and DeepL otherwise.

<table>
<thead>
  <tr>
    <th>
      Value
    </th>
    
    <th>
      Resolves to
    </th>
    
    <th>
      Panel label
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        'deepl'
      </code>
    </td>
    
    <td>
      <code>
        DeepLStrategy
      </code>
      
       – requires <code>
        DeepL.apiKey
      </code>
    </td>
    
    <td>
      <code>
        DeepL
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        'ai'
      </code>
    </td>
    
    <td>
      <code>
        CopilotAIStrategy
      </code>
      
       – requires the <a href="/copilot">
        Kirby Copilot
      </a>
      
       plugin
    </td>
    
    <td>
      no provider dialog
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        Closure
      </code>
    </td>
    
    <td>
      Wrapped in <code>
        CallableStrategy
      </code>
      
      . Signature: <code>
        fn (string $text, string $target, ?string $source): string
      </code>
    </td>
    
    <td>
      <code>
        Custom
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        Strategy
      </code>
    </td>
    
    <td>
      Used as-is – instance of <code>
        JohannSchopplich\ContentTranslator\Translation\Strategy
      </code>
    </td>
    
    <td>
      <code>
        Custom
      </code>
    </td>
  </tr>
</tbody>
</table>

The Panel follows this option: a closure or `Strategy` instance enables the translation buttons without a `DeepL.apiKey`, and `'ai'` makes Copilot the only provider on offer – with a single provider there is nothing to pick, so no dialog renders. When both are available, the AI toggle carries the name of the Copilot provider in use (`Gemini`, `GPT (OpenAI)`, `Claude`, `Mistral AI`), falling back to `AI (Copilot)`.

<code-group>

```php [String preset]
return [
    'johannschopplich.content-translator' => [
        'strategy' => 'deepl', // or 'ai'
    ]
];
```

```php [Closure]
return [
    'johannschopplich.content-translator' => [
        'strategy' => function (string $text, string $target, ?string $source): string {
            return myTranslateApi($text, $target, $source);
        },
    ]
];
```

```php [Custom Strategy]
use App\Translation\MyApiStrategy;

return [
    'johannschopplich.content-translator' => [
        'strategy' => new MyApiStrategy(),
    ]
];
```

</code-group>

<callout color="info" icon="i-ri-arrow-right-line" to="/docs/content-translator/php-classes/strategies">

See the **Strategies** reference for the full interface and built-in implementations.

</callout>

<warning>

The legacy `translateFn` option is deprecated and will be removed in v4. Migrate by renaming the key to `strategy` – the closure signature is identical.

</warning>

### `batchConcurrency` <u-badge className="align-middle,ml-2,rounded-full!" label="Integer" variant="subtle"></u-badge>

In batch translation mode, multiple languages are translated in parallel to improve performance. By default, up to 2 translations are processed concurrently to avoid hitting API rate limits.

Lower it to `1` when the provider returns rate limit errors – the languages then translate one after another:

```php [config.php]
return [
    'johannschopplich.content-translator' => [
        'batchConcurrency' => 1
    ]
];
```

### `ai.systemPrompt` <u-badge className="align-middle,ml-2,rounded-full!" label="String" variant="subtle"></u-badge>

When using AI translation, you can replace the built-in system prompt with a custom one. Set it globally or override it per blueprint.

```php [config.php]
return [
    'johannschopplich.content-translator' => [
        'ai' => [
            'systemPrompt' => 'You are a medical translator. Preserve clinical terminology and abbreviations.'
        ]
    ]
];
```

<callout color="info" icon="i-ri-sparkling-line" to="/docs/content-translator/providers/ai-translation#custom-system-prompt">

See the **AI Translation** docs for the full default prompt, blueprint override examples, and usage details.

</callout>

<callout color="info" icon="i-ri-arrow-right-line" to="/docs/content-translator/configuration/local#configuration-precedence">

For configuration precedence and blueprint overrides, see the **View Button & Section Configuration** docs.

</callout>

---

Every page of this site as Markdown: <https://kirby.tools/sitemap.md>