Skip to content

Latest commit

 

History

History
97 lines (68 loc) · 3.25 KB

README.md

File metadata and controls

97 lines (68 loc) · 3.25 KB
Raw

English | Русский

Markdown Localization (Micro) Specification

Provides a structure and workflow to localize Markdown files.

Structure

All elements are in HTML comments.

  • l10n:select - a switcher between all localizations of the file.
  • l10n:p - splits document into localizable paragraphs. All localized files have a copy of original document split into paragraphs in comments and marked with a l10n:p annotation.
  • l10n:ignore - excludes elements of content from original and localized documents from synchronization status check. Mark the beginning with l10n:ignore start and the end with l10n:ignore end.

Example that includes all of these sections: README-ru.md

Workflow

Localize new files

  1. Create new file.
  • Use the same name, as original file has.
  • Add a suffix for the supported locale.
  • Example: Original - README.md, Localized - README-it.md.
  1. Copy original file content.
  • Copy the contents of the original file to a localized file.
  • Put all paragrapgs, delimited by headers into comments with l10n:p annotations.
  1. Update headers.
  • Update the header of the original file and other localization files to include a link to a new localization file.
  1. Translate.
  • Add translations as separate paragraphs to match the structure of original file.

Update localized files

  1. Check sync status
  • Check which paragraphs were added or updated in original file.
  1. Update translation.
  • Update original paragraphs in the commented section of localized files.
  • Update translations in localized files to match original paragraphs

Workflow automation with MDLM

Workflow can be partially automated with mdlm-sh.

$ mdlm search eo
eo (Esperanto) - Esperanto
ka (ქართული) - Georgian
ty (Reo Mā`ohi) - Tahitian

$ mdlm add eo
Creating new localization files for locale - "eo (Esperanto) - Esperanto":
Creating example/README-eo.md. Confirm? [Y/n]
- Created.
Creating README-eo.md. Confirm? [Y/n]
- Created.
Finished. Total files created: 2

Now files are created and ready for translation.

Once original files are updated, check the synchronization difference between original file and localization files:

$ mdlm diff es
Localization status for - es (Español) - Spanish:
- example/README-es.md (Español) - outdated.
4c4,5
< Here is an outdated text of example.
---
> Here is a text of example.
>

Example

Example of original file with multiple locization:

Credits

Sources for languages and their native translations:

Contributing

All contributions are welcome:

  • Specification - proposals for updates and additions
  • Language tags and names - add language, update native name of the language
  • Localization of this document. Guidelines and status in LOCALIZATION.md
  • Creating new automations (Python, JavaScript, etc.)