improve l10n (goatshriek#403)

Refactors the localization build script to support building doxygen documentation in different languages when present. The Chinese localization in l10n/zh-cn has had more added to it as an example of how localization of documentation should be done.
AryasCodeTreks · Jan 25, 2024 · 8f3d535 · 8f3d535
1 parent d043a8c
commit 8f3d535
Show file tree

Hide file tree

Showing 13 changed files with 587 additions and 116 deletions.
diff --git a/.github/workflows/locale.yml b/.github/workflows/locale.yml
@@ -12,7 +12,7 @@ env:
 jobs:
   linux-de-de:
     name: "linux, de-de"
-    runs-on: "ubuntu-20.04"
+    runs-on: "ubuntu-latest"
     env:
       LANG: "de_DE.UTF-8"
     steps:
@@ -32,7 +32,7 @@ jobs:
           if grep "DEPRECATED" Testing/Temporary/LastTest.log; then exit 1; fi
   linux-cz-cz:
     name: "linux, cz-cz"
-    runs-on: "ubuntu-20.04"
+    runs-on: "ubuntu-latest"
     env:
       LANG: "cz_ES.UTF-8"
     steps:
@@ -52,7 +52,7 @@ jobs:
           if grep "DEPRECATED" Testing/Temporary/LastTest.log; then exit 1; fi
   linux-es-es:
     name: "linux, es-es"
-    runs-on: "ubuntu-20.04"
+    runs-on: "ubuntu-latest"
     env:
       LANG: "es_ES.UTF-8"
     steps:
@@ -72,7 +72,7 @@ jobs:
           if grep "DEPRECATED" Testing/Temporary/LastTest.log; then exit 1; fi
   linux-fr-fr:
     name: "linux, fr-fr"
-    runs-on: "ubuntu-20.04"
+    runs-on: "ubuntu-latest"
     env:
       LANG: "fr_FR.UTF-8"
     steps:
@@ -92,7 +92,7 @@ jobs:
           if grep "DEPRECATED" Testing/Temporary/LastTest.log; then exit 1; fi
   linux-it-it:
     name: "linux, it-it"
-    runs-on: "ubuntu-20.04"
+    runs-on: "ubuntu-latest"
     env:
       LANG: "it_IT.UTF-8"
     steps:
@@ -112,7 +112,7 @@ jobs:
           if grep "DEPRECATED" Testing/Temporary/LastTest.log; then exit 1; fi
   linux-sk-sk:
     name: "linux, sk-sk"
-    runs-on: "ubuntu-20.04"
+    runs-on: "ubuntu-latest"
     env:
       LANG: "sk_SK.UTF-8"
     steps:
@@ -132,7 +132,7 @@ jobs:
           if grep "DEPRECATED" Testing/Temporary/LastTest.log; then exit 1; fi
   linux-tr-tr:
     name: "linux, tr-tr"
-    runs-on: "ubuntu-20.04"
+    runs-on: "ubuntu-latest"
     env:
       LANG: "tr_TR.UTF-8"
     steps:
@@ -152,7 +152,7 @@ jobs:
           if grep "DEPRECATED" Testing/Temporary/LastTest.log; then exit 1; fi
   linux-pl-pl:
     name: "linux, pl-pl"
-    runs-on: "ubuntu-20.04"
+    runs-on: "ubuntu-latest"
     env:
       LANG: "pl_PL.UTF-8"
     steps:
@@ -172,7 +172,7 @@ jobs:
           if grep "DEPRECATED" Testing/Temporary/LastTest.log; then exit 1; fi
   linux-hu-hu:
     name: "linux, hu-hu"
-    runs-on: "ubuntu-20.04"
+    runs-on: "ubuntu-latest"
     env:
       LANG: "hu_HU.UTF-8"
     steps:
@@ -192,7 +192,7 @@ jobs:
           if grep "DEPRECATED" Testing/Temporary/LastTest.log; then exit 1; fi
   linux-sq-al:
     name: "linux, sq-al"
-    runs-on: "ubuntu-20.04"
+    runs-on: "ubuntu-latest"
     env:
       LANG: "sq_AL.UTF-8"
     steps:
@@ -212,7 +212,7 @@ jobs:
           if grep "DEPRECATED" Testing/Temporary/LastTest.log; then exit 1; fi
   linux-sv-se:
     name: "linux, sv-se"
-    runs-on: "ubuntu-20.04"
+    runs-on: "ubuntu-latest"
     env:
       LANG: "sv_SE.UTF-8"
     steps:
@@ -232,7 +232,7 @@ jobs:
           if grep "DEPRECATED" Testing/Temporary/LastTest.log; then exit 1; fi
   linux-bg-bg:
     name: "linux, bg-bg"
-    runs-on: "ubuntu-20.04"
+    runs-on: "ubuntu-latest"
     env:
       LANG: "bg_BG.UTF-8"
     steps:
@@ -252,7 +252,7 @@ jobs:
           if grep "DEPRECATED" Testing/Temporary/LastTest.log; then exit 1; fi
   linux-el-gr:
     name: "linux, el-gr"
-    runs-on: "ubuntu-20.04"
+    runs-on: "ubuntu-latest"
     env:
       LANG: "el_GR.UTF-8"
     steps:
@@ -272,7 +272,7 @@ jobs:
           if grep "DEPRECATED" Testing/Temporary/LastTest.log; then exit 1; fi
   linux-sw-ke:
     name: "linux, sw-ke"
-    runs-on: "ubuntu-20.04"
+    runs-on: "ubuntu-latest"
     env:
       LANG: "sw-KE.UTF-8"
     steps:
@@ -292,7 +292,7 @@ jobs:
           if grep "DEPRECATED" Testing/Temporary/LastTest.log; then exit 1; fi
   linux-pt-br:
     name: "linux, pt-br"
-    runs-on: "ubuntu-20.04"
+    runs-on: "ubuntu-latest"
     env:
       LANG: "pt_BR.UTF-8"
     steps:
@@ -312,7 +312,7 @@ jobs:
           if grep "DEPRECATED" Testing/Temporary/LastTest.log; then exit 1; fi
   linux-zh-cn:
     name: "linux, zh-cn"
-    runs-on: "ubuntu-20.04"
+    runs-on: "ubuntu-latest"
     env:
       LANG: "zh_CN.UTF-8"
     steps:
@@ -330,9 +330,12 @@ jobs:
         run: |
           make check
           if grep "DEPRECATED" Testing/Temporary/LastTest.log; then exit 1; fi
+      - name: Docs
+        run: |
+          make docs
   linux-hi-in:
     name: "linux, hi-in"
-    runs-on: "ubuntu-20.04"
+    runs-on: "ubuntu-latest"
     env:
       LANG: "hi_IN.UTF-8"
     steps:
@@ -352,7 +355,7 @@ jobs:
           if grep "DEPRECATED" Testing/Temporary/LastTest.log; then exit 1; fi
   linux-bn-in:
     name: "linux, bn-in"
-    runs-on: "ubuntu-20.04"
+    runs-on: "ubuntu-latest"
     env:
       LANG: "bn_IN.UTF-8"
     steps:
@@ -372,7 +375,7 @@ jobs:
           if grep "DEPRECATED" Testing/Temporary/LastTest.log; then exit 1; fi
   linux-da-dk:
     name: "linux, da-dk"
-    runs-on: "ubuntu-20.04"
+    runs-on: "ubuntu-latest"
     env:
       LANG: "da_DK.UTF-8"
     steps:
@@ -392,7 +395,7 @@ jobs:
           if grep "DEPRECATED" Testing/Temporary/LastTest.log; then exit 1; fi
   linux-he-il:
     name: "linux, he-il"
-    runs-on: "ubuntu-20.04"
+    runs-on: "ubuntu-latest"
     env:
       LANG: "he_IL.UTF-8"
     steps:

diff --git a/CMakeLists.txt b/CMakeLists.txt
@@ -142,6 +142,7 @@ include(tools/cmake/add_found_library.cmake)
 include(tools/cmake/benchmark.cmake)
 include(tools/cmake/example.cmake)
 include(tools/cmake/gtest.cmake)
+include(tools/cmake/l10n.cmake)
 include(tools/cmake/swig.cmake)
 include(tools/cmake/test.cmake)
 
@@ -193,74 +194,6 @@ else()
   set(STUMPLESS_DEFAULT_SOCKET "/dev/log")
 endif()
 
-# setting the chosen locale
-if(LOCALE MATCHES "^es[_-]")
-  set(STUMPLESS_LANGUAGE "es-ES")
-  set(USE_LOCALE_ES_ES TRUE)
-elseif(LOCALE MATCHES "^fr[_-]")
-  set(STUMPLESS_LANGUAGE "fr-FR")
-  set(USE_LOCALE_FR_FR TRUE)
-elseif(LOCALE MATCHES "^de[_-]")
-  set(STUMPLESS_LANGUAGE "de-DE")
-  set(USE_LOCALE_DE_DE TRUE)
-elseif(LOCALE MATCHES "^it[_-]")
-  set(STUMPLESS_LANGUAGE "it-IT")
-  set(USE_LOCALE_IT_IT TRUE)
-elseif(LOCALE MATCHES "^sv[_-]")
-  set(STUMPLESS_LANGUAGE "sv-SE")
-  set(USE_LOCALE_SV_SE TRUE)
-elseif(LOCALE MATCHES "^sk[_-]")
-  set(STUMPLESS_LANGUAGE "sk-SK")
-  set(USE_LOCALE_SK_SK TRUE)
-elseif(LOCALE MATCHES "^bg[_-]")
-  set(STUMPLESS_LANGUAGE "bg-BG")
-  set(USE_LOCALE_BG_BG TRUE)
-elseif(LOCALE MATCHES "^cz[_-]")
-  set(STUMPLESS_LANGUAGE "cz-CZ")
-  set(USE_LOCALE_CZ_CZ TRUE)
-elseif(LOCALE MATCHES "^pl[_-]")
-  set(STUMPLESS_LANGUAGE "pl-PL")
-  set(USE_LOCALE_PL_PL TRUE)
-elseif(LOCALE MATCHES "^sw[_-]")
-  set(STUMPLESS_LANGUAGE "sw-KE")
-  set(USE_LOCALE_SW_KE TRUE)
-elseif(LOCALE MATCHES "^el[_-]")
-  set(STUMPLESS_LANGUAGE "el-GR")
-  set(USE_LOCALE_EL_GR TRUE)
-elseif(LOCALE MATCHES "^pt[_-]")
-  set(STUMPLESS_LANGUAGE "pt-BR")
-  set(USE_LOCALE_PT_BR TRUE)
-elseif(LOCALE MATCHES "^zh[_-]")
-  set(STUMPLESS_LANGUAGE "zh-CN")
-  set(USE_LOCALE_ZH_CN TRUE)
-elseif(LOCALE MATCHES "^hi[_-]")
-  set(STUMPLESS_LANGUAGE "hi-IN")
-  set(USE_LOCALE_HI_IN TRUE)
-elseif(LOCALE MATCHES "^bn[_-]")
-  set(STUMPLESS_LANGUAGE "bn-IN")
-  set(USE_LOCALE_BN_IN TRUE)
-elseif(LOCALE MATCHES "^da[_-]")
-  set(STUMPLESS_LANGUAGE "da-DK")
-  set(USE_LOCALE_DA_DK TRUE)
-elseif(LOCALE MATCHES "^he[_-]")
-  set(STUMPLESS_LANGUAGE "he-IL")
-  set(USE_LOCALE_HE_IL TRUE)
-elseif(LOCALE MATCHES "^tr[_-]")
-  set(STUMPLESS_LANGUAGE "tr-TR")
-  set(USE_LOCALE_TR_TR TRUE)
-elseif(LOCALE MATCHES "^hu[_-]")
-  set(STUMPLESS_LANGUAGE "hu-HU")
-  set(USE_LOCALE_HU_HU TRUE)
-elseif(LOCALE MATCHES "^sq[_-]")
-  set(STUMPLESS_LANGUAGE "sq-AL")
-  set(USE_LOCALE_SQ_AL TRUE)
-else()
-  if(NOT LOCALE MATCHES "^en[_-]")
-    message("building default language en-US")
-  endif()
-  set(STUMPLESS_LANGUAGE "en-US")
-  set(USE_LOCALE_EN_US TRUE)
-endif()
 
 # standard source files
 set(STUMPLESS_SOURCES
@@ -1222,7 +1155,7 @@ endif()
 if(DOXYGEN_FOUND)
   configure_file(${PROJECT_SOURCE_DIR}/tools/doxygen/Doxyfile.in ${PROJECT_BINARY_DIR}/tools/doxygen/Doxyfile)
 
-  file(GLOB_RECURSE DOXYGEN_PUBLIC_HEADERS ${PROJECT_SOURCE_DIR}/include/stumpless/*.h)
+  file(GLOB_RECURSE DOXYGEN_PUBLIC_HEADERS ${DOXYGEN_INCLUDE_DIR}/stumpless/*.h)
   set(EXAMPLE_SOURCES
     ${PROJECT_SOURCE_DIR}/docs/examples/basic/basic_example.c
   )
@@ -1234,7 +1167,7 @@ if(DOXYGEN_FOUND)
     DEPENDS
       ${DOXYGEN_PUBLIC_HEADERS}
       ${EXAMPLE_SOURCES}
-      ${PROJECT_SOURCE_DIR}/include/stumpless.h
+      ${DOXYGEN_INCLUDE_DIR}/stumpless.h
       ${PROJECT_BINARY_DIR}/include/stumpless/config.h
     VERBATIM
   )

diff --git a/README.md b/README.md
@@ -1,4 +1,4 @@
-![Stumpless logo](assets/logo-and-name.svg)
+![Stumpless logo](./assets/logo-and-name.svg)
 
 **A C logging library built for high performance and a rich feature set.**
 
@@ -11,24 +11,27 @@
 [![Apache 2.0 License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
 [![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-v2.1-ff69b4.svg)](https://github.com/goatshriek/stumpless/blob/latest/docs/CODE_OF_CONDUCT.md)
 
+
+[简体中文](./l10n/zh-cn/自述.md)
+
+
 [Key Features](#key-features) |
 [Build and Install](#quick-build-and-install) |
 [Basic Usage](#basic-usage) |
 [Contributing](#contributing)
 
 
 ## Key Features
-Stumpless offers a robust set of features to make logging in C faster and
-easier:
- * easy logging to [lots of things](#what-can-it-log-to) like Splunk, rsyslog,
+Stumpless has lots of features that make logging in C fast and easy:
+ * log to [lots of things](#what-can-it-log-to) like Splunk, rsyslog,
    journald, the Windows Event Log, and more!
  * structured and unstructured logging to suit your needs
- * interoperable with common log daemons and libraries
  * builds for Linux, Windows, Mac, MinGW, MSYS2, Cygwin, and more
- * completely thread safe
- * can be adjusted or removed during compilation for zero runtime impact
- * localized for multiple languages :brazil: :bulgaria: :cn: :czech_republic:
-   :de: :es: :fr: :greece: :india: :it: :poland: :slovakia: :sweden: :tr: :us: :denmark: :israel: :kenya: :albania: :hungary:
+ * thread safe
+ * can be adjusted or removed during compilation for zero runtime cost
+ * localized for multiple languages :albania: :brazil: :bulgaria: :cn:
+   :czech_republic: :de: :denmark: :es: :fr: :greece: :hungary: :india:
+   :israel: :it: :kenya: :poland: :slovakia: :sweden: :tr: :us:
    ([add yours!](https://github.com/goatshriek/stumpless/blob/latest/docs/localization.md))
  * easy-access
    [documentation](https://goatshriek.github.io/stumpless/docs/c/latest/index.html),
@@ -46,6 +49,7 @@ and plugins to get them where you want. Stumpless can write logs to:
  * Unix sockets (such as a local syslog daemon)
  * Network Servers (IPv4 or IPv6, TCP or UDP)
  * Systemd Journald Service
+ * Sqlite3 Databases
  * Windows Event Log
  * Custom functions, for whatever else you may need!
 

diff --git a/docs/localization.md b/docs/localization.md
@@ -100,18 +100,18 @@ defined symbols to reflect your new locale. Be sure that the name of the new
 header is a valid IETF Language Tag in all lowercase letters.
 
 After adding the header itself, you will need to tie it in to the build system
-by updating the `CMakeList.txt` file, the `include/private/config.h.in`
+by updating the `tools/cmake/l10n.cmake` file, the `include/private/config.h.in`
 header template, and the locale wrapper
 `include/private/config/locale/wrapper.h`. In the CMake script, add an `elseif`
-block to the chain of conditionals responsible for determining the locale (do a
-search for `STUMPLESS_LANGUAGE` to quickly find this) following the pattern of
-the others that are already there. Next, in the private config header template,
-add a definition for the locale symbol for the new locale. This symbol should
-be of the form `USE_LOCALE_XXX` where the last portion is the RFC 5646 language
-tag in all caps with underscore separators. Again, reference the already defined
-locales to see what this should look like. Finally, in the locale wrapper header
-add an `#elseif` statement for the new locale symbol in the same order as it
-appears in the CMake build script to include the new header.
+block to the chain of conditionals responsible for determining the locale
+following the pattern of the others that are already there. Next, in the private
+config header template, add a definition for the locale symbol for the new
+locale. This symbol should be of the form `USE_LOCALE_XXX` where the last
+portion is the RFC 5646 language tag in all caps with underscore separators.
+Again, reference the already defined locales to see what this should look like.
+Finally, in the locale wrapper header add an `#elseif` statement for the new
+locale symbol in the same order as it appears in the CMake build script to
+include the new header.
 
 The last step is to add new CI builds for the new locale to make sure that
 there are no immediate problems and catch any future ones that arise. This is

diff --git a/l10n/zh-cn/README.md b/l10n/zh-cn/README.md
diff --git a/l10n/zh-cn/包含/stumpless.h b/l10n/zh-cn/包含/stumpless.h
@@ -0,0 +1,27 @@
+/* SPDX-License-Identifier: Apache-2.0 */
+
+/*
+ * Copyright 2024 Joel E. Anderson
+ *
+ * Licensed 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.
+ */
+
+
+/** @mainpage 无树桩
+ *
+ * 无树桩是一个高性能，很多特征的C日志库。
+ */
+
+/** @example basic_example.c
+ * 简单的示例。
+ */