Miksi Contentful-sisältösi ei ole vielä oikeasti monikielistä
By Robert
Miksi Contentful-sisältösi ei ole vielä oikeasti monikielistä
Contentful käsittelee paikallisia asetuksia hyvin. Voit määritellä niin monta kuin tarvitset, asettaa varajärjestyksen, vaihtaa niiden välillä editorissa ja rakentaa käyttöliittymän, joka palvelee oikeaa kieltä reitin mukaan. Monikielisen sisällön infrastruktuuri on aidosti hyvä.
Mitä Contentful ei tee, on kääntää sisältöäsi.
Tämä kuulostaa ilmeiseltä, kun se sanotaan suoraan, mutta on yllättävän helppoa sekoittaa "meillä on paikalliskentät asetettu" ja "olemme monikielisiä". Nämä kaksi eivät ole sama asia. Paikalliskentät ovat säiliö. Monikielisyys tarkoittaa, että säiliössä on sisältöä.
Jos Contentful-tilassasi on määritelty ranskan ja saksan paikalliset asetukset, mutta näiden kentät ovat tyhjiä, tai täytetty englanninkielisellä tekstillä paikkamerkkinä, tai täytetty karkealla ensimmäisellä versiolla, jota kukaan ei ole tarkistanut sivuston julkaisun jälkeen — et ole monikielinen. Sinulla on monikielisyyden runko.
Tämä kirjoitus käsittelee tämän aukon sulkemista.
Mitä Contentful oikeastaan tarjoaa sinulle
Contentfulin kielijärjestelmä on hyvin suunniteltu. Jokaisella sisältömerkinnällä voi olla kenttäarvot eri kieliversioille. Asetat oletuskielen, määrität varakielet, ja toimitus-API palauttaa oikean kieliversion pyydettäessä. Sisällön mallintaminen on tarpeeksi joustavaa käsittelemään monimutkaisia monikielisiä vaatimuksia eri sisältötyypeissä.
Mutta järjestelmä on täysin neutraali sen suhteen, miten käännetty sisältö sinne päätyy. Contentful ei tiedä, sisältävätkö ranskankieliset kenttäsi ammattimaisia käännöksiä, konekäännettyä tekstiä, vahingossa liitettyä englanninkielistä tekstiä vai ei mitään. Se vain tallentaa ja toimittaa sen, mitä laitat sisään.
Käännösongelma on täysin sinun ratkaistavasi.
Kuinka tiimit yleensä hoitavat sen (ja missä se pettää)
Useimmat Contentful-käännöksiä käsittelevät tiimit noudattavat yhtä muutamasta mallista.
Manuaalisen viennin malli. Kehittäjä vie sisältöä Contentfulista, lähettää sen käännöstoimistolle tai freelancerille, odottaa sen palautumista, muotoilee uudelleen ja tuo sisällön takaisin. Tämä toimii kertaluonteisessa julkaisussa, mutta muuttuu kestämättömäksi sisällön muuttuessa. Jokainen päivitys lähdekieleen tarkoittaa koko prosessin toistamista uudelleen. Käytännössä käännetty sisältö jää nopeasti jälkeen lähteestä, eikä kenelläkään ole aikaa päivittää sitä.
Kääntäminen editorissa -malli. Toimittaja avaa jokaisen kohteen, vaihtaa kohdekieleen ja kääntää kenttä kentältä joko manuaalisesti tai liittämällä sisältö käännöstyökaluun. Tämä on tarkkaa mutta hidasta. Se ei myöskään skaalaudu – jos sinulla on satoja kohteita useassa sisältötyypissä, manuaalisen työn määrä on merkittävä.
"Se kelpaa" -malli. Käännetty sisältö on olemassa, mutta sitä ei ole tarkistettu sen jälkeen kun se alun perin tuotettiin. Lähdekieli on päivittynyt useita kertoja sen jälkeen. Ranskan versio hinnoittelusivustasi viittaa edelleen suunnitelmaan, jonka lopetit kahdeksan kuukautta sitten. Saksan kotisivulla on edelleen vanha iskulause. Kukaan ei ole huomauttanut siitä, koska kukaan ei tarkista.
Kaikilla kolmella mallilla on sama perusongelma: käännöstä käsitellään kertaluonteisena tehtävänä sen sijaan, että se olisi jatkuva osa sisältötyönkulkua.
Mitä monikielisyys todella vaatii
Aito monikielinen sisältö Contentfulissa tarvitsee kolmea asiaa, jotka toimivat yhdessä.
Tarkka alkuperäinen käännös. Jokaisen kentän jokaisessa kohdekielessä tulee olla käännetty sisältö, joka on tarkkaa, asianmukaisesti lokalisoitua ja joka todella lukee siltä, kuin se olisi kirjoitettu kyseiselle markkinalle eikä vain peruskäännöstyökalun läpi ajettu ja tarkistamaton.
Prosessi käännösten ajantasaisuuden ylläpitämiseksi. Kun lähdesisältö muuttuu, myös käännetyn sisällön täytyy muuttua. Tämä on osa, jonka useimmat tiimit aliarvioivat. Sisältötiimi, joka julkaisee useita päivityksiä viikossa Contentful-tilassa, jossa on neljä kieliversiota ja viisikymmentä sisältötyyppiä, kohtaa merkittävän jatkuvan käännöstyön, jos se hoidetaan manuaalisesti.
Tapa tietää, milloin käännökset ovat vanhentuneita. Contentfulin kielijärjestelmä ei näytä vanhentuneisuutta. Jos päivität merkinnän englanninkielisen tekstin etkä muista päivittää ranskankielistä versiota, ranskankielinen versio jatkaa hiljaisesti vanhan sisällön näyttämistä. Tarvitset joko prosessin tai työkalun tämän havaitsemiseksi.
Missä PolyLingo sopii
PolyLingon API kääntää jäsenneltyä sisältöä säilyttäen sen rakenteen. Contentfulille relevantti formaatti on JSON — Contentful-kohteen kenttäarvot, jotka poimitaan ja lähetetään API:lle, palautuvat käännettyinä samalla rakenteella.
Perusprosessi Node.js:ssä:
import PolyLingo from 'polylingo'
import { createClient } from 'contentful-management'
const poly = new PolyLingo({ apiKey: process.env.POLYLINGO_API_KEY })
const contentful = createClient({
accessToken: process.env.CONTENTFUL_MANAGEMENT_TOKEN,
})
const space = await contentful.getSpace(process.env.CONTENTFUL_SPACE_ID)
const environment = await space.getEnvironment('master')
// Hae käännettävä kohde
const entry = await environment.getEntry('your-entry-id')
// PolyLingo käyttää BCP-47-koodeja ilman aluetta (fr, de).
// Määritä nämä Contentfulin kielikoodeiksi, jos ne eroavat (esim. fr-FR, de-DE).
const localeMap = { fr: 'fr', de: 'de' } // säädä vastaamaan tilasi kielikoodeja
// Poimi vain englanninkieliset merkkijonokentät — ohita viitteet, linkit, totuusarvot ja numerot
const sourceFields = Object.fromEntries(
Object.entries(entry.fields)
.filter(([, value]) => typeof value['en-US'] === 'string')
.map(([key, value]) => [key, value['en-US']])
)
// Käännä ranskaksi ja saksaksi yhdellä pyynnöllä
const result = await poly.translate({
content: JSON.stringify(sourceFields),
format: 'json',
targets: Object.keys(localeMap),
})
// Kirjoita käännetyt arvot takaisin kohteeseen Contentfulin kielikoodeilla
for (const [polyLocale, translated] of Object.entries(result.translations)) {
const contentfulLocale = localeMap[polyLocale]
const parsed = JSON.parse(translated)
for (const [field, value] of Object.entries(parsed)) {
if (!entry.fields[field]) entry.fields[field] = {}
entry.fields[field][contentfulLocale] = value
}
}
await entry.update()
await entry.publish()
console.log('Kohde käännetty ja julkaistu.')
Yksi API-kutsu palauttaa sekä ranskan että saksan. Kohde päivitetään ja julkaistaan samassa skriptissä.
Huomautus kielikoodeista: PolyLingo käyttää BCP-47-koodeja ilman aluepäätettä (fr, de). Contentful-tilat käyttävät usein aluekohtaisia koodeja kuten fr-FR tai de-DE. Yllä oleva localeMap-objekti on paikka, jossa ne sovitetaan yhteen — päivitä se vastaamaan tilasi kielikoodeja.
Sama malli toimii Pythonissa:
import os, json, requests
from contentful_management import Client
poly_key = os.environ['POLYLINGO_API_KEY']
contentful = Client(os.environ['CONTENTFUL_MANAGEMENT_TOKEN'])
space = contentful.spaces().find(os.environ['CONTENTFUL_SPACE_ID'])
environment = space.environments().find('master')
entry = environment.entries().find('your-entry-id')
# Poimi englanninkieliset kenttäarvot
source_fields = {
key: value.get('en-US')
for key, value in entry.fields().items()
if value.get('en-US')
}
# Käännä ranskaksi ja saksaksi
r = requests.post(
'https://api.usepolylingo.com/v1/translate',
headers={'Authorization': f"Bearer {poly_key}"},
json={
'content': json.dumps(source_fields),
'format': 'json',
'targets': ['fr', 'de'],
},
timeout=120,
)
r.raise_for_status()
translations = r.json()['translations']
# Kirjoita takaisin kohteeseen
for locale, translated in translations.items():
parsed = json.loads(translated)
for field, value in parsed.items():
if field in entry.fields():
entry.fields()[field][locale] = value
entry.save()
entry.publish()
print('Kohde käännetty ja julkaistu.')
Käännös suuressa mittakaavassa
Yllä olevat esimerkit käsittelevät yhtä merkintää. Contentful-tilassa, jossa on monia merkintöjä useiden sisältötyyppien välillä, erärajapinta käsittelee jopa 100 kohdetta kerrallaan:
// Hae useita merkintöjä ja käännä ne yhdellä eräkutsulla
const entries = await environment.getEntries({
content_type: 'blogPost',
limit: 50,
})
// Kartuta PolyLingo-kielikoodit Contentfulin kieli-ID:ihin
const localeMap = { fr: 'fr', de: 'de', es: 'es' } // säädä vastaamaan tilaasi
const items = entries.items.map(entry => ({
id: entry.sys.id,
content: JSON.stringify(
Object.fromEntries(
Object.entries(entry.fields)
.filter(([, value]) => typeof value['en-US'] === 'string')
.map(([k, v]) => [k, v['en-US']])
)
),
format: 'json',
}))
const batch = await poly.batch({
items,
targets: Object.keys(localeMap),
})
for (const result of batch.results) {
const entry = entries.items.find(e => e.sys.id === result.id)
for (const [polyLocale, translated] of Object.entries(result.translations)) {
const contentfulLocale = localeMap[polyLocale]
const parsed = JSON.parse(translated)
for (const [field, value] of Object.entries(parsed)) {
if (!entry.fields[field]) entry.fields[field] = {}
entry.fields[field][contentfulLocale] = value
}
}
await entry.update()
await entry.publish()
}
Viisikymmentä merkintää, kolme kieltä, yksi eräpyyntö.
Käännösten pitäminen ajan tasalla
Yllä olevia skriptejä voidaan suorittaa tarpeen mukaan tai liittää julkaisuprosessiisi. Yleinen käytäntö on suorittaa käännös osana CI-tehtävää, joka käynnistyy, kun lähdesisältö muuttuu, tai aikataululla, joka kattaa viimeisen 24 tunnin aikana päivitetyt merkinnät.
Contentful tukee myös webhookkeja — voit määrittää webhookin, joka aktivoituu, kun merkintä julkaistaan oletuskielessä, mikä voi automaattisesti käynnistää käännöstehtävän. PolyLingo-liittäminen tähän webhookiin tarkoittaa, että aina kun toimittaja julkaisee päivitetyn englanninkielisen sisällön, käännetyt kielet päivittyvät ilman manuaalista vaihetta. Tämä on suunnitelmissa omalle PolyLingo-integraatiolle; toistaiseksi API tarjoaa kaiken tarvittavan tämän työnkulun rakentamiseen itse.
Huomautus kenttätyypeistä
Yllä oleva lähestymistapa toimii hyvin lyhyelle tekstille, pitkälle tekstille ja rikkaalle tekstille, joka on tallennettu merkkijonoina. Muutamia Contentfulin kenttätyyppejä on käsiteltävä erikseen:
Rikkaat tekstikentät, jotka on tallennettu Contentfulin dokumenttimuodossa (eivät tavallisina merkkijonoina), on sarjoitettava tavalliseksi tekstiksi tai HTML:ksi ennen lähettämistä PolyLingolle, ja sitten purettava takaisin. @contentful/rich-text-html-renderer-paketti hoitaa sarjoitusvaiheen, ja PolyLingon puolella format: "html" säilyttää merkintäkielen oikein.
Viitekenttiä (linkkejä muihin merkintöihin tai resursseihin) ei tule kääntää — ne ovat tunnisteita, eivät tekstiä. Poista ne kentistä, jotka lähetät API:lle.
Numero-, totuusarvo- ja päivämääräkenttiä ei voi luonnostaan kääntää. Suodata ne pois ennen lähdeobjektin rakentamista.
Aloittaminen
PolyLingon ilmaisversio sisältää 50 000 tokenia kuukaudessa. Kohtuullisen sisältömäärän omaavalle Contentful-tilalle tämä kattaa alkuperäisen käännöskierroksen useissa merkinnöissä useilla kielialueilla, ja lisäksi jää tilaa jatkuville päivityksille.
Täydellinen API-dokumentaatio löytyy osoitteesta usepolylingo.com/docs. SDK-paketit ovat saatavilla Node.js:lle, Pythonille, Rubylle, PHP:lle, Javalle ja Golle.
npm install polylingo