[logging-log4cxx] 01/05: Added documentation on non-english logging

[ts...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

tschoening pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/logging-log4cxx.git

commit 8064d6afab985fb51ef403c2de79be3bb4b81ec7
Author: Robert Middleton <ro...@rm5248.com>
AuthorDate: Mon Aug 3 21:13:48 2020 -0400

    Added documentation on non-english logging
---
 src/site/markdown/non-english-logging.md | 44 ++++++++++++++++++++++++++++++++
 src/site/site.xml                        |  3 +++
 2 files changed, 47 insertions(+)

diff --git a/src/site/markdown/non-english-logging.md b/src/site/markdown/non-english-logging.md
new file mode 100644
index 0000000..d94166a
--- /dev/null
+++ b/src/site/markdown/non-english-logging.md
@@ -0,0 +1,44 @@
+<!--
+ 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 regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License.  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+
+# Non-English logging
+
+When logging messages in languages other than English, you may need to
+set your locale correctly for messages to be displayed.
+
+For example, here is some Hebrew text which says "People with disabilities":
+
+אנשים עם מוגבלות
+
+If you are to log this information on a system with a locale of `en_US.UTF-8`,
+the log message will look something like the following:
+
+```
+loggername - ?????????? ???? ??????????????
+```
+
+One way to fix this is to call `setlocale` as follows before the function that logs:
+
+```
+std::setlocale( LC_ALL, "" );
+```
+
+This will then allow the message to be logged appropriately.
+
+See issue [LOG4CXX-483][1] for more information.
+
+[1]:https://issues.apache.org/jira/browse/LOGCXX-483
diff --git a/src/site/site.xml b/src/site/site.xml
index 6941262..721a7a4 100644
--- a/src/site/site.xml
+++ b/src/site/site.xml
@@ -70,6 +70,9 @@
 			<item	name="FAQ"
 					href="/faq.html"
 			/>
+			<item	name="Non-English Logging"
+					href="/non-english-logging.html"
+			/>
 		</menu>
 
 		<menu	name="Get"