I'm submitting a...

[ ] Regression (a behavior that used to work and stopped working in a new release)
[x] Bug report  
[ ] Performance issue
[ ] Feature request
[x] Documentation issue or request
[ ] Support request => Please do not submit support request here, instead see https://github.com/angular/angular/blob/master/CONTRIBUTING.md#question
[ ] Other... Please describe:

Current behavior

Internationalization (i18n) docs are unclear and have to be read from the end.
ng serve --configuration not working

Expected behavior

Examples in docs should work.
ng serve --configuration should work.

Minimal reproduction of the problem with instructions

I followed docs and on the top there is ng serve --configuration=fr but CLI will show error, because yet there is no such configuration. So let's skip that and go on. After replace providers: [ ], with providers: [ { provide: LOCALE_ID, useValue: 'fr' } ], in the app.module.ts web browser console will show error "[object Object]" and the app will not work. Confusing... but let's try more... maybe there is needed "translation source file'? Since we've got errors at start, it is unclear if we need to create xlf file to use @angular/common/locales/... only? So, let's create that file with ng xi18n. Oh, still this: providers: [ { provide: LOCALE_ID, useValue: 'fr' } ], cause an error. Tired already? No! Let's read all the docs first. So at the end there is heading: "Merge the completed translation file into the app" and there is "configurations". I think it must have something in common with ng serve --configuration=fr at "Setting up the locale of your app" heading on the top of the document. Let's add it and try again ng serve --configuration=fr. Ooops, I've got that:

'fr' could not be found in project 'website'. Error: Configuration 'fr' could not be found in project 'website'. at Architect.getBuilderConfiguration (path\website\node_modules\@angular-devkit\architect\src\architect .js:106:23) at MergeMapSubscriber._loadWorkspaceAndArchitect.pipe.operators_1.concatMap [as project] (path\website\ node_modules\@angular\cli\models\architect-command.js:64:55) [...]

Too bad. :( Let's remove i18n lines from configuration and try again. The same error. :( Let's check ng build --configuration=fr'. It works. When used with xlf file in my configuration it shows some errors due to 3rd party modules (missing translations in xlf file, but it works. So it is possible to ng build different configurations but cannot ng serve them .

What is the motivation / use case for changing the behavior?

I need to use internalization but now it not works for me.

Environment

Angular version: X.Y.Z


Angular CLI: 6.0.8
Node: 9.5.0
OS: win32 x64
Angular: 6.0.7
... animations, common, compiler, compiler-cli, core, forms
... http, language-service, platform-browser
... platform-browser-dynamic, router

Package                           Version
-----------------------------------------------------------
@angular-devkit/architect         0.6.8
@angular-devkit/build-angular     0.6.8
@angular-devkit/build-optimizer   0.6.8
@angular-devkit/core              0.6.8
@angular-devkit/schematics        0.6.8
@angular/cli                      6.0.8
@ngtools/webpack                  6.0.8
@schematics/angular               0.6.8
@schematics/update                0.6.8
rxjs                              6.2.1
typescript                        2.7.2
webpack                           4.8.3


Browser:
For Tooling issues:
- Node version: 9.5.0
- Platform:  Windows

Others: