From 541f111cd0ec6fac862982fca159c3771cd2ae62 Mon Sep 17 00:00:00 2001 From: Maciej Bukowski Date: Tue, 28 Nov 2017 11:10:49 +0100 Subject: [PATCH 1/8] Aligned docs to the new Translation Service. --- .../guides/development/custom-builds.md | 8 ++-- .../guides/integration/advanced-setup.md | 8 +--- docs/features/ui-language.md | 42 ++++++++++++++++--- .../docs/snippet-adapter/snippetadapter.js | 2 +- 4 files changed, 43 insertions(+), 17 deletions(-) diff --git a/docs/builds/guides/development/custom-builds.md b/docs/builds/guides/development/custom-builds.md index 46c5a641530..6591a1d3462 100644 --- a/docs/builds/guides/development/custom-builds.md +++ b/docs/builds/guides/development/custom-builds.md @@ -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. + lang: 'en' } }; ``` diff --git a/docs/builds/guides/integration/advanced-setup.md b/docs/builds/guides/integration/advanced-setup.md index c72fd01cabf..dc4077262ea 100644 --- a/docs/builds/guides/integration/advanced-setup.md +++ b/docs/builds/guides/integration/advanced-setup.md @@ -11,7 +11,7 @@ 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**. @@ -19,10 +19,6 @@ Therefore, **a prerequisite to this guide is that you are using webpack as your 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. - - 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. - - First, install the build of your choice {@link builds/guides/integration/installation#npm from npm}: ```bash @@ -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' } ) ], diff --git a/docs/features/ui-language.md b/docs/features/ui-language.md index ccdb4c950bb..07f5e63c919 100644 --- a/docs/features/ui-language.md +++ b/docs/features/ui-language.md @@ -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. 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. @@ -37,8 +37,20 @@ 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 } ), // Other webpack plugins... @@ -46,10 +58,28 @@ If you build CKEditor from scratch or integrate it directly into your applicatio // ... ``` -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 + + + + ``` - 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). diff --git a/scripts/docs/snippet-adapter/snippetadapter.js b/scripts/docs/snippet-adapter/snippetadapter.js index 6ca28a4b022..e8358685271 100644 --- a/scripts/docs/snippet-adapter/snippetadapter.js +++ b/scripts/docs/snippet-adapter/snippetadapter.js @@ -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(), From e4a6e101f0df1f3de037936a1e48309e35b4f331 Mon Sep 17 00:00:00 2001 From: Maciej Bukowski Date: Tue, 28 Nov 2017 11:22:14 +0100 Subject: [PATCH 2/8] Docs fixes. --- docs/features/ui-language.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/features/ui-language.md b/docs/features/ui-language.md index 07f5e63c919..ef0a3393bda 100644 --- a/docs/features/ui-language.md +++ b/docs/features/ui-language.md @@ -58,7 +58,7 @@ If you build CKEditor from scratch or integrate it directly into your applicatio // ... ``` -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. +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. From 0f688c1af58ddcc5679c04b4103412df070c6b64 Mon Sep 17 00:00:00 2001 From: Maciej Bukowski Date: Tue, 28 Nov 2017 14:48:09 +0100 Subject: [PATCH 3/8] Changed `lang` to `languages` in docs. --- docs/builds/guides/development/custom-builds.md | 2 +- docs/features/ui-language.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/builds/guides/development/custom-builds.md b/docs/builds/guides/development/custom-builds.md index 6591a1d3462..3388d3fdbf7 100644 --- a/docs/builds/guides/development/custom-builds.md +++ b/docs/builds/guides/development/custom-builds.md @@ -111,7 +111,7 @@ module.exports = { toolbar: [ 'headings', 'bold', 'italic', 'custombutton' ], // UI language. Language codes follow the https://en.wikipedia.org/wiki/ISO_639-1 format. - lang: 'en' + language: 'en' } }; ``` diff --git a/docs/features/ui-language.md b/docs/features/ui-language.md index ef0a3393bda..b6874be19a8 100644 --- a/docs/features/ui-language.md +++ b/docs/features/ui-language.md @@ -67,7 +67,7 @@ If you build CKEditor from scratch or integrate it directly into your applicatio + +``` + +See {@link builds/guides/integration/installation#CDN CDN installation guides} for more information. + +### npm + +After installing the build from npm, languages will be available at `node_modules/@ckeditor/ckeditor5-build-[name]/build/lang/`. +Single language can be imported directly to your code by `'@ckeditor/ckeditor5-build-[name]/build/lang/de.js' )`. + +See {@link builds/guides/integration/installation#npm npm installation guides} for more information. + +### Zip + +All additional languages are included in `.zip` file. You need to include `ckeditor.js` file together with language file: + +```js + + +``` + +See {@link builds/guides/integration/installation#Zip-download zip installation guides} for more information. + ## Building the editor using a specific language 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. diff --git a/npm-debug.log b/npm-debug.log new file mode 100644 index 00000000000..ca3c81f4583 --- /dev/null +++ b/npm-debug.log @@ -0,0 +1,45 @@ +0 info it worked if it ends with ok +1 verbose cli [ '/usr/local/bin/node', '/usr/local/bin/npm', 'run', 'docs' ] +2 info using npm@3.10.10 +3 info using node@v6.10.0 +4 verbose run-script [ 'predocs', 'docs', 'postdocs' ] +5 info lifecycle ckeditor5@1.0.0-alpha.2~predocs: ckeditor5@1.0.0-alpha.2 +6 silly lifecycle ckeditor5@1.0.0-alpha.2~predocs: no script for predocs, continuing +7 info lifecycle ckeditor5@1.0.0-alpha.2~docs: ckeditor5@1.0.0-alpha.2 +8 verbose lifecycle ckeditor5@1.0.0-alpha.2~docs: unsafe-perm in lifecycle true +9 verbose lifecycle ckeditor5@1.0.0-alpha.2~docs: PATH: /usr/local/lib/node_modules/npm/bin/node-gyp-bin:/home/szymon/projects/ckeditor5/node_modules/.bin:/home/szymon/bin:/home/szymon/.local/bin:/home/szymon/bin:/home/szymon/.local/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/usr/games:/usr/local/games:/snap/bin +10 verbose lifecycle ckeditor5@1.0.0-alpha.2~docs: CWD: /home/szymon/projects/ckeditor5 +11 silly lifecycle ckeditor5@1.0.0-alpha.2~docs: Args: [ '-c', 'node ./scripts/docs/build-docs.js' ] +12 silly lifecycle ckeditor5@1.0.0-alpha.2~docs: Returned: code: 1 signal: null +13 info lifecycle ckeditor5@1.0.0-alpha.2~docs: Failed to exec docs script +14 verbose stack Error: ckeditor5@1.0.0-alpha.2 docs: `node ./scripts/docs/build-docs.js` +14 verbose stack Exit status 1 +14 verbose stack at EventEmitter. (/usr/local/lib/node_modules/npm/lib/utils/lifecycle.js:255:16) +14 verbose stack at emitTwo (events.js:106:13) +14 verbose stack at EventEmitter.emit (events.js:191:7) +14 verbose stack at ChildProcess. (/usr/local/lib/node_modules/npm/lib/utils/spawn.js:40:14) +14 verbose stack at emitTwo (events.js:106:13) +14 verbose stack at ChildProcess.emit (events.js:191:7) +14 verbose stack at maybeClose (internal/child_process.js:877:16) +14 verbose stack at Process.ChildProcess._handle.onexit (internal/child_process.js:226:5) +15 verbose pkgid ckeditor5@1.0.0-alpha.2 +16 verbose cwd /home/szymon/projects/ckeditor5 +17 error Linux 4.13.0-17-generic +18 error argv "/usr/local/bin/node" "/usr/local/bin/npm" "run" "docs" +19 error node v6.10.0 +20 error npm v3.10.10 +21 error code ELIFECYCLE +22 error ckeditor5@1.0.0-alpha.2 docs: `node ./scripts/docs/build-docs.js` +22 error Exit status 1 +23 error Failed at the ckeditor5@1.0.0-alpha.2 docs script 'node ./scripts/docs/build-docs.js'. +23 error Make sure you have the latest version of node.js and npm installed. +23 error If you do, this is most likely a problem with the ckeditor5 package, +23 error not with npm itself. +23 error Tell the author that this fails on your system: +23 error node ./scripts/docs/build-docs.js +23 error You can get information on how to open an issue for this project with: +23 error npm bugs ckeditor5 +23 error Or if that isn't available, you can get their info via: +23 error npm owner ls ckeditor5 +23 error There is likely additional logging output above. +24 verbose exit [ 1, true ] From 876826dae950feec882a4b7286c1cdab080545e1 Mon Sep 17 00:00:00 2001 From: Maciej Bukowski Date: Wed, 29 Nov 2017 11:59:13 +0100 Subject: [PATCH 5/8] Removed npm-debug.log. --- npm-debug.log | 45 --------------------------------------------- 1 file changed, 45 deletions(-) delete mode 100644 npm-debug.log diff --git a/npm-debug.log b/npm-debug.log deleted file mode 100644 index ca3c81f4583..00000000000 --- a/npm-debug.log +++ /dev/null @@ -1,45 +0,0 @@ -0 info it worked if it ends with ok -1 verbose cli [ '/usr/local/bin/node', '/usr/local/bin/npm', 'run', 'docs' ] -2 info using npm@3.10.10 -3 info using node@v6.10.0 -4 verbose run-script [ 'predocs', 'docs', 'postdocs' ] -5 info lifecycle ckeditor5@1.0.0-alpha.2~predocs: ckeditor5@1.0.0-alpha.2 -6 silly lifecycle ckeditor5@1.0.0-alpha.2~predocs: no script for predocs, continuing -7 info lifecycle ckeditor5@1.0.0-alpha.2~docs: ckeditor5@1.0.0-alpha.2 -8 verbose lifecycle ckeditor5@1.0.0-alpha.2~docs: unsafe-perm in lifecycle true -9 verbose lifecycle ckeditor5@1.0.0-alpha.2~docs: PATH: /usr/local/lib/node_modules/npm/bin/node-gyp-bin:/home/szymon/projects/ckeditor5/node_modules/.bin:/home/szymon/bin:/home/szymon/.local/bin:/home/szymon/bin:/home/szymon/.local/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/usr/games:/usr/local/games:/snap/bin -10 verbose lifecycle ckeditor5@1.0.0-alpha.2~docs: CWD: /home/szymon/projects/ckeditor5 -11 silly lifecycle ckeditor5@1.0.0-alpha.2~docs: Args: [ '-c', 'node ./scripts/docs/build-docs.js' ] -12 silly lifecycle ckeditor5@1.0.0-alpha.2~docs: Returned: code: 1 signal: null -13 info lifecycle ckeditor5@1.0.0-alpha.2~docs: Failed to exec docs script -14 verbose stack Error: ckeditor5@1.0.0-alpha.2 docs: `node ./scripts/docs/build-docs.js` -14 verbose stack Exit status 1 -14 verbose stack at EventEmitter. (/usr/local/lib/node_modules/npm/lib/utils/lifecycle.js:255:16) -14 verbose stack at emitTwo (events.js:106:13) -14 verbose stack at EventEmitter.emit (events.js:191:7) -14 verbose stack at ChildProcess. (/usr/local/lib/node_modules/npm/lib/utils/spawn.js:40:14) -14 verbose stack at emitTwo (events.js:106:13) -14 verbose stack at ChildProcess.emit (events.js:191:7) -14 verbose stack at maybeClose (internal/child_process.js:877:16) -14 verbose stack at Process.ChildProcess._handle.onexit (internal/child_process.js:226:5) -15 verbose pkgid ckeditor5@1.0.0-alpha.2 -16 verbose cwd /home/szymon/projects/ckeditor5 -17 error Linux 4.13.0-17-generic -18 error argv "/usr/local/bin/node" "/usr/local/bin/npm" "run" "docs" -19 error node v6.10.0 -20 error npm v3.10.10 -21 error code ELIFECYCLE -22 error ckeditor5@1.0.0-alpha.2 docs: `node ./scripts/docs/build-docs.js` -22 error Exit status 1 -23 error Failed at the ckeditor5@1.0.0-alpha.2 docs script 'node ./scripts/docs/build-docs.js'. -23 error Make sure you have the latest version of node.js and npm installed. -23 error If you do, this is most likely a problem with the ckeditor5 package, -23 error not with npm itself. -23 error Tell the author that this fails on your system: -23 error node ./scripts/docs/build-docs.js -23 error You can get information on how to open an issue for this project with: -23 error npm bugs ckeditor5 -23 error Or if that isn't available, you can get their info via: -23 error npm owner ls ckeditor5 -23 error There is likely additional logging output above. -24 verbose exit [ 1, true ] From ad881991c161483e659640ef3bbcc08ab0830d0f Mon Sep 17 00:00:00 2001 From: Maciej Bukowski Date: Wed, 29 Nov 2017 12:29:10 +0100 Subject: [PATCH 6/8] Docs improvements. --- docs/features/ui-language.md | 15 +++++++-------- 1 file changed, 7 insertions(+), 8 deletions(-) diff --git a/docs/features/ui-language.md b/docs/features/ui-language.md index 9a5e921a219..823322102e4 100644 --- a/docs/features/ui-language.md +++ b/docs/features/ui-language.md @@ -37,7 +37,7 @@ ClassicEditor ### CDN -To use different language than default one, you need to load the editor together with the preferred language: +To use different language than default one (English), you need to load the editor together with the preferred language: ```html @@ -48,8 +48,8 @@ See {@link builds/guides/integration/installation#CDN CDN installation guides} f ### npm -After installing the build from npm, languages will be available at `node_modules/@ckeditor/ckeditor5-build-[name]/build/lang/`. -Single language can be imported directly to your code by `'@ckeditor/ckeditor5-build-[name]/build/lang/de.js' )`. +After installing the build from npm, languages will be available at `node_modules/@ckeditor/ckeditor5-build-[name]/build/lang/[lang].js`. +Single language can be loaded directly to your code by importing `'@ckeditor/ckeditor5-build-[name]/build/lang/de.js'`. See {@link builds/guides/integration/installation#npm npm installation guides} for more information. @@ -96,12 +96,11 @@ If you build CKEditor from scratch or integrate it directly into your applicatio // 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', + // outputDirectory - optional directory for emitted translations, `'lang'` by default, relative to the webpack's output. - // Optional flag indicates breaking the build process when the error is found. - throwErrorOnMissingTranslation: false + // strict - will cause the building process to fail if an error is found during the building process. + + // verbose - will cause logging all warnings into the console } ), // Other webpack plugins... From 7816c4d3a85064d4ef14e6ce021fd9f3a86b726d Mon Sep 17 00:00:00 2001 From: Maciej Bukowski Date: Wed, 29 Nov 2017 12:39:00 +0100 Subject: [PATCH 7/8] Docs improvements. --- docs/features/ui-language.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/features/ui-language.md b/docs/features/ui-language.md index 823322102e4..e22fd340c30 100644 --- a/docs/features/ui-language.md +++ b/docs/features/ui-language.md @@ -116,9 +116,10 @@ If you build CKEditor from scratch or integrate it directly into your applicatio