How It Works
This page explains the ideas behind the editor. You don't need it to translate or to add text, but it explains why the editor behaves the way it does.
Projects, branches and strings
- A project is one app, linked to its repository and to the English file in that repository.
- A project watches one or more branches, for example a preview branch and a production branch. Each watched branch usually has its own site, such as a preview site and the live site.
- A string is one piece of text, named by a namespace (the section of the app) and a key, for example
news.subscribe_button.
From a push to the inbox
- A developer adds or changes English in the app's English file and pushes to a watched branch.
- The push notifies the editor, which reads that branch's English file and compares it with what it already has for that branch.
- New and changed strings land in the translators' inbox, grouped by project and labelled with the commit message.
This is called a sync. It happens on every push, and the same push arriving twice changes nothing. An admin can also run one by hand, and always sees what it would change before anything is written.
Irish is tied to the English it translates
Every Irish translation is saved together with the exact English it was written for, not just the key. This one rule is what keeps everything correct while English keeps changing:
- Two branches can carry different English for the same key. Each gets the Irish written for its own English.
- When the English changes, the old Irish is kept, and it is still used on any branch that still has the old English.
- When a branch is merged and the English becomes identical, the Irish already written for that English applies straight away. Merging needs no translation step.
Irish is never overwritten. Every save is a new version, so the full history of each string is kept and any earlier version can be restored.
What happens when English changes
| When this happens | Result |
|---|---|
| A new key is added | It goes to the inbox. Irish already written for the same English elsewhere is offered as a suggestion. |
| The English is reworded | Marked English changed. The translator sees the old and new English side by side with the old Irish, and can keep, edit or retranslate it. Branches still on the old English keep their Irish. |
| Only case, spacing or punctuation changed | Marked Small English edit. The Irish is still used; the translator just confirms it still fits. |
| A key is renamed but the English is the same | The Irish follows it automatically. |
| A key is removed from one branch | Only that branch stops using it. It stays in the editor while another branch still has it. |
| A key is removed from every branch | It is archived, not deleted. If the key comes back, its Irish comes back with it. |
| A translator rewords the English in the editor | The reworded English is used wherever the code still has the English it replaced. A developer's later change to that string in the code wins. |
How the Irish reaches the app
An app can get its Irish from the editor in one of two ways. The admin chooses which when the project is set up.
| Built in (recommended) | Loaded live | |
|---|---|---|
| How | Each build downloads the branch's Irish from the editor and builds it into the app. | Each visitor's browser downloads the Irish from the editor after the page loads. |
| When a save shows up | On the next deploy of that branch: after a Publish, the next code push, or a scheduled rebuild. | Within about a minute, with no deploy. |
| Visitors | Never contact the editor. Pages are rendered in Irish from the start. | Each page load makes an extra request to the editor, and text can switch from the built-in copy to the newer one after load. |
| If the editor is down | Deploys wait until it is back; the live site is unaffected. | The app keeps the copy it was built with. |
Built in is the recommended setup for new projects: visitors never depend on the editor, and translators decide when their work goes live with the Publish button. See Publishing.
The live preview
The live preview shows the real app inside the editor. When the editor opens an app in its preview, the app marks every translated string invisibly, so the editor knows which string is which on the page. This only happens inside the editor's preview: ordinary visitors never get these markers. See Live Preview.