# Çeviri Dizeleri

https://dev.wisecp.com/tr/ceviri-dizeleri

Çeviri dizelerini arayan, düzenleyen, silen ve taşıyan beş uç.

## Genel Bakış

Çeviri dizeleri veritabanında değil **dosyalarda** yaşar. Her dizenin bir **tam anahtarı** vardır ve o anahtar hangi dosyada durduğunu da söyler: `needs/button-save` gibi.

Anahtarın başı dizeyi üç kümeden birine yerleştirir: müşteri yüzü, yönetim paneli ve geri kalan sistem metinleri. Arama sonucu bu üç küme altında gruplanır.

Yazmanın iki yolu vardır ve **bilerek farklıdırlar**. Toplu düzenleme katıdır: tanımadığı bir anahtar gördüğünde hiçbir şey yazmaz. İçe aktarma hoşgörülüdür: tanımadığını atlar, gerisini yazar.

## Referans

### Çevirilerde Arama

get/api/v1/admin/languages/{key}/translations

`Languages/GetLanguageTranslations` admin en çok 100 eşleşme

Aradığınız metni taşıyan çeviri dizelerini gruplu döndürür.

Sorgu 1

searchstringreqAranacak metin. En az üç karakter olmalıdır ve büyük küçük harf ayrımı vardır.

Dönen alanlar data — 3 + meta — 3

clientobject clientMüşteri yüzündeki eşleşmeler.

totalintGruptaki eşleşme sayısı.

dataobjectTam anahtar ile değeri eşleyen harita.

adminobjectYönetim panelindeki eşleşmeler.

systemobjectKalan bütün eşleşmeler. Hata mesajları ve ortak metinler.

totalintToplanan eşleşme sayısı. Yüzde durur, gerçek toplam daha büyük olabilir.

searchstringAradığınız metin.

truncatedboolYüz sınırına ulaşıldı mı.

Hatalar 3

language_not_found404Dil bulunamadı.

search_too_short422Arama metni üç karakterden kısa.

insufficient_scope403Anahtar gerekli kapsamı taşımıyor.

İstek cURL JavaScript PHP (HTTP) PHP (Dahili)

```bash
curl 'https://panel.ornek.com/api/v1/admin/languages/de/translations?search=Save' \
  -H "Authorization: Bearer $API_KEY"
```

```javascript
const url = new URL(`https://panel.ornek.com/api/v1/admin/languages/${key}/translations`);
url.searchParams.set('search', term);

const res  = await fetch(url, { headers: { Authorization: `Bearer ${apiKey}` } });
const { data, meta } = await res.json();
if (meta.truncated) narrowTheSearch();
```

```php
$qs = http_build_query(['search' => $term]);
$ch = curl_init('https://panel.ornek.com/api/v1/admin/languages/' . $key . '/translations?' . $qs);
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ['Authorization: Bearer ' . $apiKey],
]);

$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```

```php
// Arama BUYUK-KUCUK harfe duyarlidir: 'save' ile 'Save' ayni sonucu vermez.
$r = Api::Languages()->GetLanguageTranslations(['key' => $key], ['search' => 'Save']);
if ($r['meta']['truncated']) $logger->info('sonuc yuzde kesildi — aramayi daraltin');
```

### Çevirileri Toplu Düzenleme

put/api/v1/admin/languages/{key}/translations

`Languages/UpdateLanguageTranslations` admin katı

Verdiğiniz anahtarların karşılıklarını yazar, gerisine dokunmaz.

Gövde 1

translationsobjectreqTam anahtar ile yeni değeri eşleyen harita. Bir anahtar bile geçersizse istek tümüyle reddedilir.

Dönen alanlar data — 2

updatedintYazılan anahtar sayısı.

languagestringDilin anahtarı.

Hatalar 4

language_not_found404Dil bulunamadı.

translations_required422Harita boş.

invalid_translation_key422Bir anahtar var olmayan bir dosyaya işaret ediyor.

insufficient_scope403Anahtar gerekli kapsamı taşımıyor.

İstek cURL JavaScript PHP (HTTP) PHP (Dahili)

```bash
curl -X PUT 'https://panel.ornek.com/api/v1/admin/languages/de/translations' \
  -H "Authorization: Bearer $API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"translations":{"needs/button-save":"Speichern"}}'
```

```javascript
const res = await fetch(`https://panel.ornek.com/api/v1/admin/languages/${key}/translations`, {
  method: 'PUT',
  headers: {
    Authorization: `Bearer ${apiKey}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    translations: {
      'needs/button-save': 'Speichern',
      'admin/services/page-list': 'Dienste',
    },
  }),
});

const body = await res.json();
```

```php
$ch = curl_init('https://panel.ornek.com/api/v1/admin/languages/' . $key . '/translations');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST  => 'PUT',
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer ' . $apiKey,
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'translations' => ['needs/button-save' => 'Speichern'],
    ]),
]);

$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```

```php
// TEK gecersiz anahtar tum yigini reddeder; toplu yukleme icin ice aktarma ucunu secin.
Api::Languages()->UpdateLanguageTranslations([
    'key' => $key, 'translations' => ['needs/button-save' => 'Speichern'],
]);
```

### Tek Çeviriyi Silme

delete/api/v1/admin/languages/{key}/translations

`Languages/DeleteLanguageTranslation` admin

Tek bir çeviri dizesini dosyasından kaldırır.

Gövde 1

keystringreqSilinecek tam çeviri anahtarı. Adresteki dil anahtarıyla karıştırmayın.

Dönen alanlar data — 3

deletedboolSilme çalıştı mı.

keystringSilinen çeviri anahtarı.

languagestringDilin anahtarı.

Hatalar 5

language_not_found404Dil bulunamadı.

key_required422Çeviri anahtarı verilmedi.

invalid_translation_key422Çeviri anahtarı geçersiz.

translation_file_not_found404Anahtarın işaret ettiği dosya yok.

insufficient_scope403Anahtar gerekli kapsamı taşımıyor.

İstek cURL JavaScript PHP (HTTP) PHP (Dahili)

```bash
curl -X DELETE 'https://panel.ornek.com/api/v1/admin/languages/de/translations' \
  -H "Authorization: Bearer $API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"key":"needs/button-save"}'
```

```javascript
const res = await fetch(`https://panel.ornek.com/api/v1/admin/languages/${lang}/translations`, {
  method: 'DELETE',
  headers: {
    Authorization: `Bearer ${apiKey}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ key: 'needs/button-save' }),
});

const body = await res.json();
```

```php
$ch = curl_init('https://panel.ornek.com/api/v1/admin/languages/' . $lang . '/translations');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST  => 'DELETE',
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer ' . $apiKey,
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode(['key' => 'needs/button-save']),
]);

$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```

```php
// Silinen anahtari arayan ekran BOS metin basar; ceviriyi bosaltmak yerine duzeltmeyi dusunun.
Api::Languages()->UpdateLanguageTranslations([
    'key' => $lang, 'translations' => ['needs/button-save' => 'Speichern'],
]);
```

### Çevirileri Dışa Aktarma

get/api/v1/admin/languages/{key}/translations/export

`Languages/ExportLanguageTranslations` admin

Dilin bütün çeviri dizelerini düz bir harita olarak döndürür.

Dönen alanlar data + meta — 2

dataobjectTam anahtar ile değeri eşleyen düz harita. İçe aktarma ucuna doğrudan verilebilir.

countintDize sayısı. Meta altında döner.

languagestringDilin anahtarı.

Hatalar 2

language_not_found404Dil bulunamadı.

insufficient_scope403Anahtar gerekli kapsamı taşımıyor.

İstek cURL JavaScript PHP (HTTP) PHP (Dahili)

```bash
curl 'https://panel.ornek.com/api/v1/admin/languages/de/translations/export' \
  -H "Authorization: Bearer $API_KEY" > de.json
```

```javascript
const res = await fetch(`https://panel.ornek.com/api/v1/admin/languages/${key}/translations/export`, {
  headers: { Authorization: `Bearer ${apiKey}` },
});

const { data, meta } = await res.json();
console.log(`${meta.count} dize`);
```

```php
$ch = curl_init('https://panel.ornek.com/api/v1/admin/languages/' . $key . '/translations/export');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ['Authorization: Bearer ' . $apiKey],
]);

$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```

```php
// Cikti JSON'dur, tablo dosyasi DEGIL; panelin sundugu tablo bicimi bu ucta yoktur.
$dump = Api::Languages()->ExportLanguageTranslations(['key' => $key])['data'];
file_put_contents("$key.json", json_encode($dump, JSON_PRETTY_PRINT | JSON_UNESCAPED_UNICODE));
```

### Çevirileri İçe Aktarma

post/api/v1/admin/languages/{key}/translations/import

`Languages/ImportLanguageTranslations` admin hoşgörülü

Bir çeviri haritasını toplu yazar ve tanımadığı anahtarları atlar.

Gövde 1

translationsobjectreqTam anahtar ile değeri eşleyen harita. Dışa aktarma çıktısıyla aynı biçimdedir.

Dönen alanlar data — 4

languagestringDilin anahtarı.

translationsintGönderdiğiniz anahtar sayısı.

applied_filesintYazılan dosya sayısı.

skipped_filesarrayHedef dosyası bulunmadığı için atlanan anahtarlar. Sessiz kaybın tek işaretidir.

Hatalar 3

language_not_found404Dil bulunamadı.

translations_required422Harita boş.

insufficient_scope403Anahtar gerekli kapsamı taşımıyor.

İstek cURL JavaScript PHP (HTTP) PHP (Dahili)

```bash
curl -X POST 'https://panel.ornek.com/api/v1/admin/languages/de/translations/import' \
  -H "Authorization: Bearer $API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"translations":{"needs/button-save":"Speichern"}}'
```

```javascript
const res = await fetch(`https://panel.ornek.com/api/v1/admin/languages/${key}/translations/import`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${apiKey}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ translations: map }),
});

const { data } = await res.json();
if (data.skipped_files.length) reportSkipped(data.skipped_files);
```

```php
$ch = curl_init('https://panel.ornek.com/api/v1/admin/languages/' . $key . '/translations/import');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer ' . $apiKey,
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode(['translations' => $map]),
]);

$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```

```php
// Tanimadigi anahtari SESSIZCE atlar; atlananlari saymazsaniz eksik ceviri fark edilmez.
$out = Api::Languages()->ImportLanguageTranslations(['key' => $key, 'translations' => $map])['data'];
if ($out['skipped_files']) $logger->warning('atlanan anahtar', $out['skipped_files']);
```

## Tuzaklar

> **Toplu düzenleme ile içe aktarma aynı hatayı farklı karşılar**
> 
> Toplu düzenleme tek bir geçersiz anahtar yüzünden **tüm yığını** reddeder ve hiçbir şey yazmaz. İçe aktarma aynı anahtarı sessizce atlar, gerisini yazar. Elle düzeltmede birincisini, dış bir dosyayı yüklerken ikincisini seçin.

> **Atlanan anahtarlar yalnız yanıtta görünür**
> 
> İçe aktarma atladığı anahtarları `skipped_files` altında sayar ve başka hiçbir yerde bildirmez. Yanıtı okumayan bir betik, çevirilerin bir bölümünü yazmadığını **hiç öğrenemez**. Bu alanı her koşuda denetleyin.

> **Arama sayısı bir toplam değildir**
> 
> Arama yüzüncü eşleşmede durur ve `total` alanı **toplanan** sayıyı verir, var olan toplamı değil. `truncated` doğruysa daha fazlası vardır ve kaç tane olduğu bilinmez. Bu sayıyı bir ilerleme göstergesine bağlamayın.

> **Arama büyük küçük harfe duyarlıdır**
> 
> Arama metni birebir karşılaştırılır: `save` aramak `Save` dizesini bulmaz. Bir metni tüm kurulumda değiştirmeye çalışıyorsanız aynı kelimeyi her yazımıyla ayrı ayrı arayın.

> **İki farklı anahtar, tek istek**
> 
> Silme ucunda adres **dil anahtarını**, gövde ise **çeviri anahtarını** taşır. İkisi de `key` adını kullanır. Gövdeye dil anahtarını yazmak geçersiz çeviri anahtarı hatası verir; bunu dilin bulunamaması sanmayın.

> **Dışa aktarma bir tablo dosyası vermez**
> 
> Panelin sunduğu tablo çıktısı ile uzaktan çekme bu uçlarda **yoktur**; dışa aktarma düz bir harita döndürür ve içe aktarma aynı haritayı bekler. İkisi birbirinin simetriğidir, yani bir dili dışa aktarıp başka bir kuruluma olduğu gibi yükleyebilirsiniz.

## İlgili Makaleler

- [Dil Paketleri](https://dev.wisecp.com/tr/dil-paketleri)
- [Başvuru Listeleri](https://dev.wisecp.com/tr/basvuru-listeleri)