Update the README

l20n · Apr 20, 2017 · 6b5be5c · 6b5be5c
1 parent 8d1e88e
commit 6b5be5c
Show file tree

Hide file tree

Showing 3 changed files with 44 additions and 93 deletions.
diff --git a/README.md b/README.md
@@ -4,14 +4,13 @@ L20n: Localization 2.0 [![Build Status][travisimage]][travislink]
 [travisimage]: https://travis-ci.org/l20n/l20n.js.svg?branch=master
 [travislink]: https://travis-ci.org/l20n/l20n.js
 
-L20n reinvents software localization. Users should be able to benefit from the 
-entire expressive power of a natural language.  L20n keeps simple things 
-simple, and at the same time makes complex things possible.
+L20n is an opinionated localization library for the Web.  It builds on top of
+Project Fluent which was designed to unleash the expressive power of the
+natural language.
 
-L20n.js is a localization framework for websites which want to offer 
-a best-in-class translation experience for their users.  L20n takes advantage 
-of modern web technologies to offer a fast and lean localization of HTML and 
-JavaScript.
+L20n.js is a good choice for websites which want to offer a best-in-class
+translation experience for their users.  L20n takes advantage of modern web
+technologies to offer a fast and lean localization of HTML and JavaScript.
 
 
 How to use L20n
@@ -23,95 +22,47 @@ Include the following code in the `<head>` section of your HTML:
 <meta name="defaultLanguage" content="en-US">
 <meta name="availableLanguages" content="de, en-US, fr, pl">
 <link rel="localization" href="locales/myApp.{locale}.ftl">
-<script defer src="dist/bundle/web/l20n.js"></script>
+<script defer src="dist/web/l20n.js"></script>
 ```
+Use the `data-l10n-id` attribute on an HTML element to mark it as localizable.
 
-L20n is targeted at modern browsers.  See [docs/compat][] for documentation on 
-how to enable support for legacy browsers.
-
-[docs/compat]: https://github.com/l20n/l20n.js/blob/master/docs/compat.md
-
-
-What L20n's syntax looks like
------------------------------
-
-A straight-forward example in English:
-
-```properties
-brand-name = Firefox
-about      = About { brand-name }
-settings   = { brand-name } Settings
-```
-
-And the same thing in Polish:
-
-```properties
-brand-name =
- *[nominative]   Firefox
-  [genitive]     Firefoksa
-  [dative]       Firefoksowi
-  [accusative]   Firefoksa
-  [instrumental] Firefoksem
-  [locative]     Firefoksie
-about      = O { brand-name[locative] }
-settings   = Ustawienia { brand-name[genitive] }
+```html
+<p data-l10n-id="about"></p>
 ```
 
-Visit [FTL by Example](http://l20n.org/learn) to learn more about the FTL 
-syntax.  If you're a tool author you may be interested in the formal 
-[EBNF grammar][].
-
-[EBNF grammar]: https://github.com/l20n/spec/blob/master/grammar.ebnf
-
-
-Localizing Web content with HTML Bindings
-------------------------------------------
-
-You can take advantage of HTML bindings to localize your HTML documents with 
-L20n.  See [docs/html][] for documentation and examples.
+That's it!  L20n will set up a `MutationObserver` and will make sure the
+element is localized even if the DOM changes.  See [docs/html][] for more
+information.
 
 [docs/html]: https://github.com/l20n/l20n.js/blob/master/docs/html.md
 
-
-The JavaScript API and documentation
-------------------------------------
-
 It is also possible to use L20n programmatically, for instance in order to 
-localize dynamic content.  The API is exposed under `document.l10n`.  Refer to 
-[docs/observer][] and [docs/localization][] for more details.
-
-[docs/observer]: https://github.com/l20n/l20n.js/blob/master/docs/observer.md
-[docs/localization]: https://github.com/l20n/l20n.js/blob/master/docs/localization.md
+localize dynamic content.  The API is exposed under `document.l10n`.  Refer to
+the [docs/][] directory for more details.
 
+[docs/]: https://github.com/l20n/l20n.js/blob/master/docs/
 
-Discuss
--------
+L20n is targeted at modern browsers.  See [docs/compat][] for documentation on 
+how to enable support for legacy browsers.
 
-We'd love to hear your thoughts on L20n!  Whether you're a localizer looking 
-for a better way to express yourself in your language, or a developer trying to 
-make your app localizable and multilingual, or a hacker looking for a project 
-to contribute to, please do get in touch on the mailing list and the IRC 
-channel.
+[docs/compat]: https://github.com/l20n/l20n.js/blob/master/docs/compat.md
 
- - mailing list: https://lists.mozilla.org/listinfo/tools-l10n
- - IRC channel: [irc://irc.mozilla.org/l20n](irc://irc.mozilla.org/l20n)
 
+Learn the FTL syntax
+--------------------
 
-Get Involved
-------------
+L20n uses Project Fluent under the hood.  FTL is a localization file format
+used for describing translation resources.  FTL stands for _Fluent Translation
+List_.
 
-L20n is open-source, licensed under the Apache License, Version 2.0.  We 
-encourage everyone to take a look at our code and we'll listen to your 
-feedback.
+FTL is designed to be simple to read, but at the same time allows to represent
+complex concepts from natural languages like gender, plurals, conjugations,
+and others.
 
-We use Bugzilla to track our work. Visit our [Tracking] page for a collection 
-of useful links and information about our release planning.  You can also go 
-straight to the [Dashboard][] or [file a new bug][].
+    hello-user = Hello, { $username }!
 
-We <3 GitHub, but we prefer `text/plain` patches over pull requests.  Refer to 
-the [Contributor's documentation][]  for more information.
+[Read the Fluent Syntax Guide][] in order to learn more about the syntax.  If
+you're a tool author you may be interested in the formal [EBNF grammar][].
 
-[Tracking]: https://wiki.mozilla.org/L20n/Tracking 
-[Dashboard]: https://bugzilla.mozilla.org/page.cgi?id=productdashboard.html&product=L20n&bug_status=open&tab=summary
-[file a new bug]: https://bugzilla.mozilla.org/enter_bug.cgi?product=L20n
-[Contributor's documentation]: https://developer.mozilla.org/en-US/docs/L20n/Contribute
+[Read the Fluent Syntax Guide]: http://projectfluent.io/fluent/guide/
+[EBNF grammar]: https://github.com/projectfluent/fluent/tree/master/spec
diff --git a/docs/gecko.rst b/docs/gecko.rst
@@ -128,14 +128,14 @@ allowed in the translation as well. Consider the following source HTML::
 Assume the following malicious translation::
 
     save =
-        | <input value="Save" type="text"> or
-        | <a
-        |     href="http://myevilwebsite.com"
-        |     onclick="alert('pwnd!')"
-        |     title="Back to the homepage"
-        | >
-        |     cancel
-        | </a>.
+        <input value="Save" type="text"> or
+        <a
+            href="http://myevilwebsite.com"
+            onclick="alert('pwnd!')"
+            title="Back to the homepage"
+        >
+            cancel
+        </a>.
 
 The result will be::
 

diff --git a/docs/html.md b/docs/html.md
@@ -17,7 +17,7 @@ l20n.js file as the first deferred script in the `head` element.
 ```html
 <head>
   …
-  <script defer src="./node_modules/l20n/dist/bundle/web/l20n.js"></script>
+  <script defer src="./node_modules/l20n/dist/web/l20n.js"></script>
 </head>
 ```
 
@@ -113,7 +113,7 @@ The JavaScript API
 ------------------
 
 It is also possible to use L20n programmatically, for instance in order to 
-localize dynamic content.  The API is exposed under `document.l10n`.  Refer to 
-[docs/bindings][] for more details.
+localize dynamic content.  The API is exposed under `document.l10n`.  Refer to
+the [docs/][] directory for more details.
 
-[docs/bindings]: https://github.com/l20n/l20n.js/blob/master/docs/bindings.md
+[docs/]: https://github.com/l20n/l20n.js/blob/master/docs/