Author: marcus
Date: Sat Jul 26 18:58:35 2014
New Revision: 1613705
URL: http://svn.apache.org/r1613705
Log:
Updated text with more help, especially for handling the JS variables in the
files "/index.html" and "/download.index.html"
Modified:
openoffice/site/trunk/content/website-native.mdtext
Modified: openoffice/site/trunk/content/website-native.mdtext
URL:
http://svn.apache.org/viewvc/openoffice/site/trunk/content/website-native.mdtext?rev=1613705&r1=1613704&r2=1613705&view=diff
==============================================================================
--- openoffice/site/trunk/content/website-native.mdtext (original)
+++ openoffice/site/trunk/content/website-native.mdtext Sat Jul 26 18:58:35 2014
@@ -1,4 +1,4 @@
-Title:
+Title: How to edit the Native Language (NL) Websites?
Notice: Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements. See the NOTICE file
distributed with this work for additional information
@@ -19,18 +19,18 @@ Notice: Licensed to the Apache Softwa
## Native Language (NL) Websites
Apache OpenOffice supports users around the world via our many OpenOffice
localizations, via
-native language mailing lists and support forums, and by translations of our
website. This
-page describes the steps to create and maintain an NL website. Following
these steps you
-can create a website translation like our
[Spanish](http://www.openoffice.org/es),
-[Turkish](http://www.openoffice.org/tr) or
[Dutch](http://www.openoffice.org/nl) websites.
+native language mailing lists and support forums, and by translations of our
website. This
+page describes the steps to create and maintain an NL website. Following these
steps you
+can create a website translation like our
[Spanish](http://www.openoffice.org/es/),
+[Turkish](http://www.openoffice.org/tr/) or
[Dutch](http://www.openoffice.org/nl/) websites.
-Making updates to the Apache OpenOffice project's websites is simple. It's
even easy
+Making updates to the Apache OpenOffice project's websites is simple. It's
even easy
for non-committers (new contributors - like you) to create a patch to request
that
pages are updated by the project community.
## The XX Website
-The easiest way to get started is with the [XX
website](http://www.openoffice.org/xx).This
+The easiest way to get started is with the [XX
website](http://www.openoffice.org/xx/).This
website is a extract of the most-commonly visited pages from the English
website, including:
* The home page
@@ -45,45 +45,55 @@ want to translate.
## Creating the Test Directory
In many cases there will already be an NL website for your language, but
perhaps one that is
-badly out-of-date or is non-standard. However, until your new translation is
ready to go it
-is probably best not to wipe out the existing NL page. So initially you will
probably want
+badly out-of-date or is non-standard. However, until your new translation is
ready to go it
+is probably best not to wipe out the existing NL page. So initially you will
probably want
to do your work in a test directory.
-Let's take an example. Suppose your target language is Italian (it). You
will want to do
-the following. If you are not a Committer and are not familiar with
Subversion then you will
-want to get help with these steps by asking on the mailing list.
-
- 1. Make a copy (svn copy) of the [ooo-site/trunk/content/xx
directory](https://svn.apache.org/repos/asf/openoffice/ooo-site/trunk/content/xx/)
- as ooo-site/trunk/content/test-it. In the copy replace all instances of
"/xx"
-in paths with "/test-it".
- 1. Also make a copy of
[ooo-site/trunk/templates/xx](https://svn.apache.org/repos/asf/openoffice/ooo-site/trunk/templates/xx/)
+**Let's take an concreate example:**
+<br />
+Suppose your target language is Italian (it). You will want to do
+the following. If you are not a Committer and are not familiar with Subversion
then you
+will want to get help with these steps by asking on the mailing list.
+
+1. Make a copy (svn copy) of the
+[ooo-site/trunk/content/xx
directory](https://svn.apache.org/repos/asf/openoffice/ooo-site/trunk/content/xx/)
+as ooo-site/trunk/content/test-it. In the copy replace all instances of "/xx"
in paths,
+files and also within files with "/test-it".
+1. Also make a copy of
+[ooo-site/trunk/templates/xx](https://svn.apache.org/repos/asf/openoffice/ooo-site/trunk/templates/xx/)
and call the copy ooo-site/trunk/templates/test-it.
- 1. Commit these changes and publish via the CMS
- 1. If you are a committer then you can translate the contents of the files in
/test-it locally
-or via the CMS, whatever you prefer. If you are not a committer than ask
someone to do an
-"svn export" of the new /test-it and send a ZIP file of the contents.
+1. Commit these changes and publish via the CMS
+1. If you are a committer then you can translate the contents of the files in
/test-it
+locally or via the CMS, whatever you prefer. If you are not a committer than
ask someone
+to do an "svn export" of the new /test-it and send a ZIP file of the contents.
+
+**Important:**
+<br />
+In any case, the complete "/xx" directory and its files are used as a template.
+Please always copy it to a different location first before you start any
editing!
## Translating the Website
The files will be in two main formats:
- 1. HTML files.
- 1. Markdown text files. You can read more about Markdown Text
[here](http://daringfireball.net/projects/markdown/basics).
+1. HTML files.
+1. Markdown text files.
+[Need to know more about Markdown
Text?](http://daringfireball.net/projects/markdown/basics)
-In your translation, do not change the file or directory names. Be careful to
preserve the
-markup of the HTML and the indentation levels of the MDText files.
+In your translation, do not change the file or directory names. Be careful to
preserve
+the markup of the HTML and the indentation levels of the MDText files.
## The Template
-You will notice that there is more on the openoffice.org website than what you
see in the
-/test-it content files. The content files give the central part of each page,
but the header,
-footer as well as navigation menus are generated by the template. There are
special MDText
-files that you will need to translate for the template. They are:
-
- - /xx/topnav.mdtext
- - /xx/why/leftnav.mdtext
- - /xx/product/leftnav.mdtext
- - /xx/brand.mdtext
+You will notice that there is more on the openoffice.org website than what you
see in the
+/test-it content files. The content files give the central part of each page,
but the
+header, footer as well as navigation menus are generated by the template.
There are special
+MDText files that you will need to translate for the template. They are:
+
+- /xx/topnav.mdtext
+- /xx/why/leftnav.mdtext
+- /xx/product/leftnav.mdtext
+- /xx/brand.mdtext
For example, the /xx/topnav.mdtext has lines like this:
@@ -91,59 +101,128 @@ For example, the /xx/topnav.mdtext has l
[Download][m1]
[Support][m2]
-Here you should translate the words "Product", "Download" and "Support".
Also, at the
+Here you should translate the words "Product", "Download" and "Support". Also,
at the
bottom of the file you will see hyperlinks, which should not be changed, and
text hints for
the hyperlinks which should be translated.
-A special word about brand.mdtext. This contains several values that control
the overall
-branding on the website. The name and logo must not be changed, since these
are our
-trademarks, but the "tagline" can be translated. Note also the announcement
and
-announcementurl fields. These control the blue announcement that is the top
of every website
-page. That should be translated and the URL changed if needed. For example,
in a new release
-you would want to point to a translated version of the release notes, if they
exist.
+A special word about brand.mdtext. This contains several values that control
the overall
+branding on the website. The name and logo must not be changed, since these
are our
+trademarks, but the "tagline" can be translated. Note also the announcement and
+announcement url fields. These control the blue announcement that is the top
of every
+website page. That should be translated and the URL changed if needed. For
example, in a
+new release you would want to point to a translated version of the release
notes, if they
+exist.
## Other Hints
A few other things to watch out for.
- 1. Some files contain an Apache License header at the top of the page. You
should not translate that.
- 1. Some files contain comments. These don't need to be translated, but no
harm is done if they are.
- 1. The /download/index.html requires special care since some of the language
strings are within
-Javascript blocks. Ask for help if you need it here.
- 1. It is easy to miss the social networking messages in /download/index.html.
These are in the HTML
-header block and in function shareTwitter(). The string is something like
"Join the OpenOffice revolution, the free office productivity suite with over
60 million trusted downloads."
-You should translate these, but adapt if needed to keep the Twitter string
within the 140 limit for Twitter.
+1. Some files contain an Apache License header at the top of the page. You
should not
+translate that.
+1. Some files contain comments. These don't need to be translated, but no harm
is done if
+they are.
+1. The /download/index.html requires special care since the language strings
are stored in
+a the separate Javascript file "msg_prop_l10n_xx.js". The file "index.html"
contains only
+the variables. Look for the further section if you need more help on this.
+1. It is easy to miss the social networking messages in /download/index.html.
+These are in the HTML header block and in function shareTwitter(). The string
is something
+like "Join the OpenOffice revolution, the free office productivity suite with
over 100
+million trusted downloads."
+You should translate these, but adapt if needed to keep the Twitter string
within the 140
+limit for Twitter.
+
+## How to find the right text for the file at the right place?
+
+All texts, mouse over titles and link URLs that can be localized are collected
in the
+"msg_prop_l10n_xx.js" files. The variables are named and sorted via the
sections they are
+displayed in and have also comments to keep the overview.
+
+**Example:**
+<br />
+// Extensions: Strings in the blue box (top) (used in "index.html").
+<br />
+Here the text for the headline in the blue box for the extensions is stored:
+<br />
+l10n.dl_ext_blue_box_headline_text = "Get Apache OpenOffice Extensions and
Dictionaries";
+
+Please note that not all text is always displayed. Some are only shown in case
of errors to
+handle a special behavior.
+
+**Example:**
+<br />
+// Download: Strings for error text in the sub-red box (used in "download.js").
+<br />
+Here the text for the left download button is shown when the selected options
do not lead to
+a correct download:
+<br />
+l10n.dl_full_link_error_text = "No full installation available";
+
+## You can see the variables and text but cannot find the respective file(s)?
+
+The "msg_prop_l10n_xx.js" files contains already a lot of strings. But it is
maybe not
+wished to localize everything that is existing. So, we can keep the "/xx"
example section
+small.
+
+For example, the following variables point to files that are not existing yet.
You have to
+create them first:
+
+l10n.dl_analyze_headline_text = "How to report a broken download link?";
+<br />
+--> "analyze.html"
+
+l10n.dl_help_link = "http://www.openoffice.org/download/full_vs_lp.html";;
+<br />
+--> "full_vs_lp.html"
+
+Also many links in the navigation bar referes to global webpages.
## NL-Specific Content
-It may be desired to add language-specific custom content to the website. For
example:
+It may be desired to add language-specific custom content to the website. For
example:
- - A localized Arabic website might want a special page dedicated to a
description of how
-to use the bidirectional text features in OpenOffice. The Tamil website might
want a page
+- A localized Arabic website might want a special page dedicated to a
description of how
+to use the bidirectional text features in OpenOffice. The Tamil website might
want a page
that links to a particular open source font download that is recommended.
- - There may be a local OpenOffice-related event that you want to publicize.
+- There may be a local OpenOffice-related event that you want to publicize.
-New content pages can be added to your NL directory and links page from a
navigator or from
-a news article on the home page as appropriate.
+New content pages can be added to your NL directory and links page from a
navigator or
+from a news article on the home page as appropriate.
## After Translation
-Once your translation is done, you can check it in (if you are a committer) or
ask someone to help
-you check it in and publish it to the website. Review the published pages to
verify that the
-translation is as you want it, and that all links work. Once it is ready you
can rename your
-"test" directory and make it the new NL website for your language!
-
-Please Note: If there is an existing NL website it is recommended that you do
the switch over like this:
-
- 1. First delete the existing NL page, e.g., svn del /it. Commit and publish
that change.
- 1. Then rename the content/test-it directory, e.g., svn move content/test-it
content/it.
- 1. Also rename the templates/test-it to /templates/it
- 1. Commit these changes and commit them via the CMS
-
-This order is recommended, with the commit and publish after the deletion of
the old directory,
-due to a CMS build issue we've run into if all these steps are done together
in a single commit.
+Once your translation is done, you can check it in (if you are a committer) or
ask someone
+to help you check it in and publish it to the website. Review the published
pages to verify
+that the translation is as you want it, and that all links work. Once it is
ready you can
+rename your "test" directory and make it the new NL website for your language!
+
+**Please Note:**
+<br />
+If there is an existing NL website it is recommended that you do the switch
+over like this:
+
+1. First delete the existing NL page, e.g., svn del /it. Commit and publish
that change.
+1. Then rename the content/test-it directory, e.g., svn move content/test-it
content/it.
+1. Also rename the templates/test-it to /templates/it
+1. Commit these changes and commit them via the CMS
+
+This order is recommended, with the commit and publish after the deletion of
the old
+directorym due to a CMS build issue we've run into if all these steps are done
together in
+a single commit.
## Maintaining NL Websites
-Do try to check your NL website every few weeks to see if any changes are
needed. Try to keep it in sync
-with the English website. Is there a new announcement header? A new release?
A new blog post?
+Do try to check your NL website every few weeks to see if any changes are
needed. Try to
+keep it in sync with the English website. Is there a new announcement header?
A new
+release? A new blog post?
+
+## You got stuck and need help?
+
+You can always refer to the global webpages at "http://www.openoffice.org/";.
The directory
+and file structure is the same.
+
+## You need a helping hand?
+
+You can get in contact with us via the
+[L10N mailing
list](http://openoffice.apache.org/mailing-lists.html#localization-mailing-list-public).
+See the general explaination for
+[what a mailing list
is](http://openoffice.apache.org/mailing-lists.html#using-mailing-lists).
