Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Align docs to the new Translation Service #694

Merged
merged 8 commits into from
Nov 30, 2017
Merged

Align docs to the new Translation Service #694

Show file tree
Hide file tree
Changes from 3 commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
541f111
Aligned docs to the new Translation Service.
ma2ciek Nov 28, 2017
e4a6e10
Docs fixes.
ma2ciek Nov 28, 2017
0f688c1
Changed `lang` to `languages` in docs.
ma2ciek Nov 28, 2017
2e7b446
Changes to 'Setting the UI language' feature documentation.
szymonkups Nov 29, 2017
876826d
Removed npm-debug.log.
ma2ciek Nov 29, 2017
ad88199
Docs improvements.
ma2ciek Nov 29, 2017
7816c4d
Docs improvements.
ma2ciek Nov 29, 2017
b776391
Bumped up `ckeditor5-dev-webpack-plugin`.
ma2ciek Nov 30, 2017
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 4 additions & 4 deletions docs/builds/guides/development/custom-builds.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -106,12 +106,12 @@ module.exports = {
'../relative/path/to/some/othercustomplugin'
],

// UI language. Language codes follow the https://en.wikipedia.org/wiki/ISO_639-1 format.
language: 'en',

// Editor configuration.
config: {
toolbar: [ 'headings', 'bold', 'italic', 'custombutton' ]
toolbar: [ 'headings', 'bold', 'italic', 'custombutton' ],

// UI language. Language codes follow the https://en.wikipedia.org/wiki/ISO_639-1 format.
language: 'en'
}
};
```
Expand Down
8 changes: 2 additions & 6 deletions docs/builds/guides/integration/advanced-setup.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,18 +11,14 @@ In this guide, we would like to show you ways to closer integrate CKEditor with

## Bundler

CKEditor 5 is currently built using [webpack](https://webpack.js.org) (>=2.x.x). All builds, examples and demos are generated using this bundler. It should also be possible to build CKEditor using other bundlers (if they are configured properly), such as [Rollup](https://github.com/rollup/rollup) or [Browserify](http://browserify.org/) but these setups are not officially supported yet. Also, the [`@ckeditor/ckeditor5-dev-webpack-plugin`](https://www.npmjs.com/package/@ckeditor/ckeditor5-dev-webpack-plugin) that allows to localize the editor is only available for webpack. More work on this subject will be done after v1.0.0.
CKEditor 5 is currently built using [webpack](https://webpack.js.org) (>=3.x.x). All builds, examples and demos are generated using this bundler. It should also be possible to build CKEditor using other bundlers (if they are configured properly), such as [Rollup](https://github.com/rollup/rollup) or [Browserify](http://browserify.org/) but these setups are not officially supported yet. Also, the [`@ckeditor/ckeditor5-dev-webpack-plugin`](https://www.npmjs.com/package/@ckeditor/ckeditor5-dev-webpack-plugin) that allows to localize the editor is only available for webpack. More work on this subject will be done after v1.0.0.

Therefore, **a prerequisite to this guide is that you are using webpack as your build tool**.

## Scenario 1: Integrating existing builds

This is the simplest scenario. It assumes that you want to use {@link builds/guides/overview#Available-builds one of the existing builds} "as-is" (you can, of course, still {@link builds/guides/integration/configuration configure the editor}). It also gives the fastest build times.

<info-box>
At the current stage, builds are only available in English. {@link features/ui-language Setting editor UI language} requires rebuilding the editor which means that this scenario is quite limited.
</info-box>

First, install the build of your choice {@link builds/guides/integration/installation#npm from npm}:

```bash
Expand Down Expand Up @@ -119,7 +115,7 @@ module.exports = {

new CKEditorWebpackPlugin( {
// See https://ckeditor5.github.io/docs/nightly/ckeditor5/latest/features/ui-language.html
languages: [ 'pl' ]
language: 'pl'
} )
],

Expand Down
42 changes: 36 additions & 6 deletions docs/features/ui-language.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ See the demo of the editor in German:

## Building the editor using a specific language

Currently, it is only possible to change the UI language at the build stage. A single build of the editor supports only the language which was defined in the [CKEditor 5 webpack plugin](https://www.npmjs.com/package/@ckeditor/ckeditor5-dev-webpack-plugin)'s configuration.
Currently, it is possible to change the UI language at the build stage and after the build. A single build of the editor supports the language which was defined in the [CKEditor 5 webpack plugin](https://www.npmjs.com/package/@ckeditor/ckeditor5-dev-webpack-plugin)'s configuration. See the whole translation process to see how you can change the language later.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This guide needs to be pretty much rewritten rather than patched. Since the whole picture changed dramatically we need to put focus on different things.

  1. The current intro can stay.

  2. But then we should explain how to initialize the editor from CDN/zip/npm with a different language. This is what most people will want to do. Please also review other guides like installation.md and other places where we list files available in a build because that list needs to be updated (and perhaps link to the ui-language.md guide):

    image

  3. Then we can provide a few more details on what other options people have:

    • compiling an optimised editor (single language case),
    • compiling a subset of languages (TBH, I'm not sure what's the use case for that – perhaps speeding up the process and reducing the number of files – but let's mention it anyway),
    • handling multiple entry points scenario (as @ma2ciek noticed that has certain limitations)

  4. At the end we can mention that compiling editor translations is only available for Webpack and we will be extending support for other bundlers in the future. If we want to mention those tickets about translations services we should explain why we mention them. Something like – if you'd like to tinker with one of the bundlers you can read about CKEditor 5's translation service here and here.


If you use one of the {@link builds/index predefined editor builds}, refer to {@link builds/guides/development/custom-builds Creating custom builds} to learn how to change the language of your build.

Expand All @@ -37,19 +37,49 @@ If you build CKEditor from scratch or integrate it directly into your applicatio
// Define webpack plugins ...
plugins: [
new CKEditorWebpackPlugin( {
// Note: The plugin is currently able to build just one language at a time.
languages: [ 'pl' ]
// Main language that will be built in to the main bundle.
language: 'en',

// Additional languages that will be emitted to the `outputDirectory`.
// This option can be set to array of language codes or `'all'` to build all found languages.
// The bundle is optimized for one language when this option is omitted.
additionalLanguages: 'all',

// Optional directory for emitted translations, `'lang'` by default.
// Relative to the webpack's output.
outputDirectory: 'lang',

// Optional flag indicates breaking the build process when the error is found.
throwErrorOnMissingTranslation: false
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is false a default value? In documentation, in code samples, we should present real usage and no one will change false to false :P Plus, the comment above is unclear now – if you'd turn it on here, we could simply document that it "Will cause the building process to fail if a translation for one of the strings is missing".

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ok. I just wanted to list available options with their default values.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You can mention the default value of each option in a comment.

} ),

// Other webpack plugins...
]
// ...
```

3. Run webpack. The CKEditor plugin for webpack will replace the {@link module:utils/locale~Locale#t `t()`} function calls used in the source code with localized language strings.
3. Run webpack. If the `additionalLanguages` option is not set, the CKEditor plugin for webpack will replace the {@link module:utils/locale~Locale#t `t()`} function call parameters used in the source code with localized language strings. Otherwise the CKEditor plugin for webpack will replace the {@link module:utils/locale~Locale#t `t()`} function call parameters with short ids and emit the translation files that should land in the `'lang'` directory (or different, if the `outputDirectory` option is specified).

4. If you want to change the language after the build ends, you will need to edit the `index.html` file, add the translation file and set the UI language to the target one.

```html
<script src="../build/ckeditor.js"></script>
<script src="../build/lang/pl.js"></script>
<script>
ClassicEditor.create( document.querySelector( '#editor' ), {
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Better Consistent formatting:

ClassicEditor
    .create( {
    } )
    .then()
    .catch();

language: 'pl'
} )
.then( editor => {
window.editor = editor;
} )
.catch( err => {
console.error( err.stack );
} );
</script>
```

<info-box>
We are aware that the current localization method is not sufficient for all needs. It neither supports different bundlers (e.g. Rollup or Browserify) nor building multiple languages (to make it possible to pick one at runtime). We will be extending the localization possiblities in the near future.
We are aware that the current localization method is not sufficient for all needs. It doesn't support different bundlers (e.g. Rollup or Browserify). We will be extending the localization possibilities in the future.

You can read more about the used techniques and future plans in the ["Implement translation services" issue](https://github.com/ckeditor/ckeditor5/issues/387).
You can read more about the used techniques in the ["Implement translation services" issue](https://github.com/ckeditor/ckeditor5/issues/387) and ["Implement translation services v2" issue](https://github.com/ckeditor/ckeditor5/issues/624).
</info-box>
2 changes: 1 addition & 1 deletion scripts/docs/snippet-adapter/snippetadapter.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -88,7 +88,7 @@ function getWebpackConfig( config ) {
const plugins = [
new ExtractTextPlugin( 'snippet.css' ),
new CKEditorWebpackPlugin( {
languages: [ config.language || 'en' ]
language: config.language || 'en'
} ),
new webpack.BannerPlugin( {
banner: bundler.getLicenseBanner(),
Expand Down