payload-crowdin-sync
v0.39.0TypeScript
Automatically upload/sync localized fields from the default locale to Crowdin. Make these fields read-only in other locales and update them using Crowdin translations.
0/weekUpdated 3 months agoISCUnpacked: 489.7 KB
Published by https://github.com/thompsonsj
npm install payload-crowdin-syncPayload Crowdin Sync Plugin
Automatically upload/sync localized fields from the default locale to Crowdin. Load translations from Crowdin into Payload CMS.
Table of contents:
- Install
- Database changes
- Options
- Sync translations
- Further documentation
Install
- Payload version 3.0 or higher is required
``
#npm
npm install payload-crowdin-sync
yarn
yarn add payload-crowdin-sync
`
Add the plugin to your Payload configuration.
ts
import { crowdinSync } from 'payload-crowdin-sync';export default buildConfig({
plugins: [
crowdinSync({
projectId: 323731,
token: process.env.CROWDIN_TOKEN,
organization: process.env.CROWDIN_ORGANIZATION,
localeMap: {
de_DE: {
crowdinId: 'de',
},
fr_FR: {
crowdinId: 'fr',
},
},
sourceLocale: 'en',
}),
],
// The rest of your config goes here
});
`Database changes
This plugin add three collections to your database:
-
-
- Localized documents have an extra field added to them -
.For details, see docs/crowdin.md.
Options
$3
Your Crowdin project ID.
`js
{
projectId: 323731,
}
`$3
Map your Payload locales to Crowdin locale ids.
js
{
localeMap: {
de_DE: {
crowdinId: 'de',
}
}
}
`$3
The Payload locale that syncs to source translations (files) on Crowdin.
js
{
sourceLocale: 'en',
}
`$3
Your Crowdin API token. If empty, changes to files are disabled.
js
{
token: 'xxxxxxx',
}
`$3
Your Crowdin organization ID.
js
{
organizationId: 200000000,
}
`$3
Crowdin directory ID to store translations. To get the directory ID without making an API call, inspect the page source of your folder in Sources > Files.
js
{
directoryId: 1169,
}
`$3
Define an array of collection slugs for which the plugin is active.
js
{
collections: ['posts', 'categories'],
}
`If undefined, the plugin will detect localized fields on all collections.
js
{
collections: undefined,
}
`Use an empty array to disable all collections.
js
{
collections: [],
}
`Use an object to define a condition that activates Crowdin based on the document data.
js
{
collections: [
'posts',
{
slug: 'categories',
condition: ({ doc }) => doc.translateWithCrowdin,
},
];
}
`$3
Define an array of global slugs for which the plugin is active.
js
{
globals: ['nav'],
}
`If undefined, the plugin will detect localized fields on all globals.
js
{
globals: undefined,
}
`Use an empty array to disable all globals.
js
{
globals: [],
}
`Use an object to define a condition that activates Crowdin based on the document data.
js
{
globals: [
{
slug: 'nav',
condition: ({ doc }) => doc.translateWithCrowdin,
},
],
}
`$3
Pass a custom config for the
serializer used to convert Payload CMS Slate JSON to HTML for Crowdin translation. See Serializer configuration.`js
{
slateToHtmlConfig: undefined,
}
`$3
Pass a custom config for the
serializer used to conver HTML to Payload CMS Slate JSON when retrieving Crowdin translation. See Serializer configuration.`js
{
htmlToSlateConfig: undefined,
}
`$3
collection config to pass to all the Crowdin collections created by this plugin.`js
{
pluginCollectionAccess: undefined,
}
`$3
collection config to pass to all the Crowdin collections created by this plugin.`js
{
pluginCollectionAdmin: {
hidden: ({ user }) => !userIsAdmin({ user });
}
}
`$3
Appends
tab onto your config using Payload's Tabs Field. If your collection is not already tab-enabled, meaning the first field in your config is not of type tabs, then one will be created for you called Content.`js
{
tabbedUI: true,
}
`$3
Default
. Used as a prefix when constructing directory names for Lexical block fields in Crowdin.`js
{
lexicalBlockFolderPrefix: blocks-,
}
`$3
Set
to update all localized fields in Crowdin when an article is created/updated.By default, updates will only be sent to Crowdin in the following scenarios.
- At least one of the localized text fields has changed: any change to a localized
text field updates the compiled fields.json that is sent to Crowdin.
- A richText field is changed. Individual richText fields will only be updated on Crowdin if the content has changed - each field has its own file on Crowdin.It is useful to have a convenient way of forcing all localized fields to update at once. For example, if the plugin is activated on an existing install, it is convenient to trigger all updates on Crowdin for a given article without having to change every
richText field or one of the text fields.Sync translations
$3
On save draft or publish, content from localized fields in Collections and/or globals is organised into directories and files in your Crowdin project as configured in options.
#### Exclude fields
In some cases, you may wish to localize fields but prevent them being synced to Crowdin. e.g. a slug field that autogenerates based on title.
There are two ways to indicate to the plugin that a field should be ignored. In your field config:
- add
{ custom: { crowdinSync: { disable: true } }} (preferred); or
- include the string Not sent to Crowdin. Localize in the CMS. in admin.description (may be removed in a future version).Example:
`ts
import type { Field } from 'payload';const field: Field = {
name: 'textLocalizedField',
type: 'text',
localized: true,
custom: {
crowdinSync: {
disable: true,
},
},
};
`$3
To load translations into Payload CMS, use either:
- virtual fields added to each localized document (convenient); or
- endpoints added to the API (can do a dry run of changes).
#### Virtual fields
When in a locale other than the source locale:
- Check the
checkbox on a given collection document/global and save draft (loads translations as draft) or publish.
- Check the Sync translations checkbox to synchronise for the current locale only.
Set a
PAYLOAD_CROWDIN_SYNC_USE_JOBS environment variable to a non-empty value (e.g. true) to add translation sync operations as jobs. This is a useful way to prevent hooks from running slowly. You'll need to execute the job queue seperately. See
Queues | Docs | Payload CMS.#### Endpoints
API endpoints are added to the
crowdin-article-directories collection.##### Review (dry run)
To review translations, visit:
e.g.
A JSON object is returned that allows you to review what will be updated in the database. The JSON object will contain the following keys:
-
indicates that on update, a draft will be created rather than a published version. See Drafts | Payload CMS.
- source review the source document. e.g. for the en locale.
- translations
- e.g. es_ES
- all current localized fields and values.
- currentTranslations localized fields populated with values from Crowdin.
- changed boolean to indicate whether any changes have been made in Crowdin.##### Update
To update translations, visit:
e.g.
The document will be updated and the same report will be generated as for a review.
##### Notes
- Pass the
query parameter to update as a draft rather than a published version.
- Pass a locale parameter to perform a review/update for one locale only. e.g. locale=fr_FR.
- The source locale (e.g. en) is not affected.
- Use the excludeLocales field on documents in the crowdin-article-directories` collection to prevent some locales from being included in the review/update operation.- If supplied translations do not contain required fields, translation updates will not be applied and validation errors will be returned in the API response.
Further documentation
- Development guidance: docs/development.md
- Engineering decisions: docs/enginering.md
- Crowdin collections: docs/crowdin.md
- NX generated docs: docs/nx.md
Note: This plugin is still in development. A todo list is maintained at docs/development.md.