Migrate Internationalization How_to_add_things_to_the_Eclipse_doc to

markdown

Also fixes a link in Eclipse_Doc_Style_Guide

Author: vogella

docs/Eclipse_Doc_Style_Guide.md

@@ -95,6 +95,4 @@ Contents
 | --- | --- |
 | Eclipse indexes its help files by looking at the text in the page and weighting titles over paragraphs. However, there can be times when you want the index to show text that does not display on the page. For example, if Eclipse uses its own terminology for a function, you might want users to be able to look up synonyms.  To have the Eclipse index generate a hit for "autosave" (a function that Eclipse has under another name) add a meta "keywords" tag before the </head> tag.   |                    <meta name="keywords" content="autosave">           |
 
-* * *
-Back to [Eclipse Documentation](/Eclipse_Documentation "Eclipse Documentation")
 

docs/How_to_add_things_to_the_Eclipse_doc.md

@@ -0,0 +1,73 @@
+How to add things to the Eclipse doc
+====================================
+
+Contents
+--------
+
+*   [1 Adding new plug-ins and dependencies](#Adding-new-plug-ins-and-dependencies)
+*   [2 Adding new API packages](#Adding-new-API-packages)
+*   [3 Adding new extension points](#Adding-new-extension-points)
+*   [4 JDT and PDE docs](#JDT-and-PDE-docs)
+*   [5 Missing API docs](#Missing-API-docs)
+
+Adding new plug-ins and dependencies
+------------------------------------
+
+To add new plug-ins and plug-in dependencies, you need to make changes in several places in the org.eclipse.platform.doc.isv plug-in (which is located in the eclipse.platform.common Git repository):
+
+1.  platformOptions.txt
+    *   the plug-in's source folder(s) must be included on the -sourcepath
+        *   remember to remove the plug-in from -classpath if it was already there
+    *   code of required plug-ins must be added on the -classpath (unless they are already on the -sourcepath)
+        *   non-JARed plug-ins: Path(s) to the JAR(s)
+        *   JARed plug-ins: <plugin>/@dot
+        *   plug-ins not built during the platform build: path to the built JAR  
+            **Caveat:** the JAR name typically contains a version:
+            *   Either remember to update the version in the reference whenever a new version is used
+            *   Or (since 3.8 incl. maintenance branches) replace the `_<major>.<minor>.<service>.<qualifier>` with `_*` if only one version of the JAR is present during the build.
+    *   the API package names must be included in the (alphabetical) package list at the end of the file
+    *   variables like `${eclipse.platform.resources.bundles}` are resolved from `cbi_basedirs.properties` (and `pde_basedirs.properties` for the old PDE-based build)
+2.  buildDoc.xml
+    *   If a plug-in contributes extension points, it should be added to the list of plug-ins in the <convertSchemaToHTML> task in the buildDoc.xml of the corresponding documentation plug-in.
+3.  plugin.xml
+    *   If your plugin has Javadoc API, add a line to plugin.xml under the org.eclipse.pde.core.javadoc extension to associate your plug-in's Javadoc with the reference section for this doc plug-in.
+
+Adding new API packages
+-----------------------
+
+1.  package.html
+    *   Create a package.html or package-info.java file for your API package, and place it in the package alongside the source code
+2.  topics_Reference.xml
+    *   add a line for each API package
+3.  reference/misc/overview-platform.html
+    *   add the API packages to the corresponding section
+4.  platformOptions.txt
+    *   the API package names must be included in the (alphabetical) package list at the end of the file
+
+Adding new extension points
+---------------------------
+
+1.  reference/extension-points/index.html
+    *   add a line for each extension point
+2.  topics_Reference.xml
+    *   add a line for each extension point
+
+JDT and PDE docs
+----------------
+
+For org.eclipse.jdt.doc.isv, the process is the same with these file location differences:
+
+*   platformOptions.txt -> jdtOptions.txt
+*   overview-platform.html -> /reference/misc/overview-jdt.html
+
+For org.eclipse.pde.doc.user, the process is the same with these file location differences:
+
+*   platformOptions.txt -> pdeOptions.txt
+*   overview-platform.html -> /reference/misc/overview-pde.html
+
+Missing API docs
+----------------
+
+org.eclipse.ua.tests.doc has an ApiDocTest that can help you detect missing API docs. The output generated by the test can be found in the Console Output Log, e.g.: [http://download.eclipse.org/eclipse/downloads/drops4/R-4.6.2-201611241400/testresults/ep46M-unit-mac64\_macosx.cocoa.x86\_64_8.0/org.eclipse.ua.tests.doc.AllTests.txt](http://download.eclipse.org/eclipse/downloads/drops4/R-4.6.2-201611241400/testresults/ep46M-unit-mac64_macosx.cocoa.x86_64_8.0/org.eclipse.ua.tests.doc.AllTests.txt)
+
+

docs/Internationalization.md

@@ -0,0 +1,39 @@
+
+
+Internationalization
+====================
+
+This page is a hub for resources relating to preparing Eclipse for use in other languages and locales (also known by the abbreviation [i18n](s://en.wikipedia.org/wiki/I18n)). 
+This work involves translating strings into other languages (often called NLS for Natural Language Support), handling bi-directional text (BIDI), and preparing content such as dates and times in a format appropriate for a given locale.
+
+Tools Used
+----------
+
+Some Eclipse plug-ins use ICU4J APIs when working with locale-specific content.
+
+Most Eclipse plug-ins use a special [Eclipse message bundle](http://www.eclipse.org/eclipse/platform-core/documents/3.1/message_bundles.html) mechanism for working with translated strings. This mechanism uses traditional Java message.properties files, but without using String-based keys. This has much better memory usage characteristics than traditional approaches.
+
+Bidi
+----
+
+For Bidirectional locales, like Arabic and Hebrew, some new Bidi-specific APIs were added to Eclipse 3.2 that inject directional markers into strings with implicit left-to-right meaning (such as file paths and URLs) in order to render them properly when the text is mixed. This was a necessary due to an apparent bug in rendering these strings containing mixed text on Windows. The problem appears more frequently on Windows platforms (vs Linux), but has also been found to occur on Linux in certain cases. See the Unicode [Bidirectional algorithm](http://www.unicode.org/reports/tr9/) for the specifics on how strings are normally rendered in bidirectional locales.
+
+When to externalize strings
+---------------------------
+
+Generally speaking, there are two possible audiences for a message string in your code: Eclipse plug-in programmers or end users. Messages directed at end users should be translated. Messages for the developers of the plug-in in question should not be translated. This is because the plug-in programmer likely does not understand the language being used by any given end user. If the user reports a problem and provides data such as their error log, the programmer needs to be able to understand that information. Similarly, the programmer may be running tests on different locales where they don't understand the end user strings, but need to understand error and tracing information being produced while running in that locale. Since all plug-in documentation and the code itself is written in English, it is assumed that the plug-in developers are able to understand English programming messages.
+
+The following are specific examples of strings that **should** be translated:
+
+*   Messages appearing in the GUI (editors, views, dialogs, etc).
+*   Messages explicitly returned by programmatic API (IStatus messages, messages in checked exceptions, etc)
+*   Messages printed to the console by command line tools directed at end users
+*   Messages in Ant tasks
+
+The following are specific examples of strings that should **not** be translated:
+
+*   Messages that only ever go to the log
+*   Debugging trace messages (such as those managed by the Equinox DebugOptions, and DebugTrace API), or other strings printed to stderr
+*   Messages in unchecked exceptions (RuntimeException or Error)
+
+