From 70cb48d9a8d6653b02113dd4e67b1a35c5fb6472 Mon Sep 17 00:00:00 2001 From: Elvis Mao Date: Wed, 7 Aug 2024 23:21:57 +0800 Subject: [PATCH 1/5] Chiense config --- docs/docusaurus.config.js | 10 +++++++++- .../docusaurus-plugin-content-blog/options.json | 14 ++++++++++++++ .../docusaurus-plugin-content-docs/current.json | 10 ++++++++++ .../current/api-key.md | 15 +++++++++++++++ 4 files changed, 48 insertions(+), 1 deletion(-) create mode 100644 docs/i18n/zh-Hant/docusaurus-plugin-content-blog/options.json create mode 100644 docs/i18n/zh-Hant/docusaurus-plugin-content-docs/current.json create mode 100644 docs/i18n/zh-Hant/docusaurus-plugin-content-docs/current/api-key.md diff --git a/docs/docusaurus.config.js b/docs/docusaurus.config.js index 0068aa4..12fbac1 100755 --- a/docs/docusaurus.config.js +++ b/docs/docusaurus.config.js @@ -13,6 +13,10 @@ module.exports = { favicon: 'img/favicon.ico', organizationName: user, // Usually your GitHub org/user name. projectName: project, // Usually your repo name. + i18n: { + defaultLocale: 'en', + locales: ['en', 'zh-Hant'], + }, themeConfig: { prism: { additionalLanguages: ["php"] @@ -24,7 +28,11 @@ module.exports = { src: 'img/logo.svg', }, items: [ - {to: 'docs/getting-started', label: 'Docs', position: 'left'}, + {to: 'docs/getting-started', label: 'Docs', position: 'left'}, + { + type: 'localeDropdown', + position: 'left', + }, { href: githubUrl, label: 'GitHub', diff --git a/docs/i18n/zh-Hant/docusaurus-plugin-content-blog/options.json b/docs/i18n/zh-Hant/docusaurus-plugin-content-blog/options.json new file mode 100644 index 0000000..cf655cb --- /dev/null +++ b/docs/i18n/zh-Hant/docusaurus-plugin-content-blog/options.json @@ -0,0 +1,14 @@ +{ + "title": { + "message": "部落格", + "description": "The title for the blog used in SEO" + }, + "description": { + "message": "部落格", + "description": "The description for the blog used in SEO" + }, + "sidebar.title": { + "message": "最新文章", + "description": "The label for the left sidebar" + } +} diff --git a/docs/i18n/zh-Hant/docusaurus-plugin-content-docs/current.json b/docs/i18n/zh-Hant/docusaurus-plugin-content-docs/current.json new file mode 100644 index 0000000..12eab05 --- /dev/null +++ b/docs/i18n/zh-Hant/docusaurus-plugin-content-docs/current.json @@ -0,0 +1,10 @@ +{ + "version.label": { + "message": "當前版本", + "description": "The label for version current" + }, + "sidebar.someSidebar.category.APIs": { + "message": "APIs", + "description": "The label for category APIs in sidebar someSidebar" + } +} diff --git a/docs/i18n/zh-Hant/docusaurus-plugin-content-docs/current/api-key.md b/docs/i18n/zh-Hant/docusaurus-plugin-content-docs/current/api-key.md new file mode 100644 index 0000000..4c5ad41 --- /dev/null +++ b/docs/i18n/zh-Hant/docusaurus-plugin-content-docs/current/api-key.md @@ -0,0 +1,15 @@ +--- +title: API 金鑰 +--- + +所有請求都需要從 OpenWeatherMap 獲取的免費 API 金鑰（有時稱為 "APPID"）。 +要獲取您的 API 金鑰，請[註冊 OpenWeatherMap 帳戶](https://home.openweathermap.org/users/sign_up)。 + +在您收到 API 金鑰後，**可能需要 ["幾個小時"](https://openweathermap.org/appid) 才能激活！其他用戶[報告](https://github.com/cmfcmf/OpenWeatherMap-PHP-API/issues/46) 大約需要 10 分鐘** 才能使 API 金鑰生效。 + +請注意 OpenWeatherMap 提供數據的許可證。撰寫本文時，所有數據均按照 **CC BY-SA 4.0** 授權，即使是付費帳戶也是如此。然而，請記住，本項目與 OpenWeatherMap 無關，這些信息可能已過時，且我無法給您法律建議。請務必自行查看條款和條件： + +- https://openweathermap.org/terms +- https://openweathermap.org/price + +*如果您的 API 金鑰或帳戶存在問題，請[直接聯繫 OpenWeatherMap](https://openweathermap.force.com/s/contactsupport) 而不是提交問題，因為我很可能無法幫助您解決帳戶問題。* \ No newline at end of file From c9b04a4ca76d3a97cfdae057fabf458d71ea4df9 Mon Sep 17 00:00:00 2001 From: Elvis Mao Date: Wed, 7 Aug 2024 23:22:17 +0800 Subject: [PATCH 2/5] Chinese Translation --- docs/i18n/zh-Hant/code.json | 309 ++++++++++++++++++ .../docusaurus-theme-classic/footer.json | 50 +++ .../docusaurus-theme-classic/navbar.json | 18 + 3 files changed, 377 insertions(+) create mode 100644 docs/i18n/zh-Hant/code.json create mode 100644 docs/i18n/zh-Hant/docusaurus-theme-classic/footer.json create mode 100644 docs/i18n/zh-Hant/docusaurus-theme-classic/navbar.json diff --git a/docs/i18n/zh-Hant/code.json b/docs/i18n/zh-Hant/code.json new file mode 100644 index 0000000..afd4b00 --- /dev/null +++ b/docs/i18n/zh-Hant/code.json @@ -0,0 +1,309 @@ +{ + "theme.ErrorPageContent.title": { + "message": "此頁已當機。", + "description": "The title of the fallback page when the page crashed" + }, + "theme.blog.archive.title": { + "message": "歷史文章", + "description": "The page & hero title of the blog archive page" + }, + "theme.blog.archive.description": { + "message": "歷史文章", + "description": "The page & hero description of the blog archive page" + }, + "theme.BackToTopButton.buttonAriaLabel": { + "message": "回到頂部", + "description": "The ARIA label for the back to top button" + }, + "theme.blog.paginator.navAriaLabel": { + "message": "部落格文章列表分頁導覽", + "description": "The ARIA label for the blog pagination" + }, + "theme.blog.paginator.newerEntries": { + "message": "較新的文章", + "description": "The label used to navigate to the newer blog posts page (previous page)" + }, + "theme.blog.paginator.olderEntries": { + "message": "較舊的文章", + "description": "The label used to navigate to the older blog posts page (next page)" + }, + "theme.blog.post.paginator.navAriaLabel": { + "message": "部落格文章分頁導覽", + "description": "The ARIA label for the blog posts pagination" + }, + "theme.blog.post.paginator.newerPost": { + "message": "較新一篇", + "description": "The blog post button label to navigate to the newer/previous post" + }, + "theme.blog.post.paginator.olderPost": { + "message": "較舊一篇", + "description": "The blog post button label to navigate to the older/next post" + }, + "theme.blog.post.plurals": { + "message": "{count} 篇文章", + "description": "Pluralized label for \"{count} posts\". Use as much plural forms (separated by \"|\") as your language support (see https://www.unicode.org/cldr/cldr-aux/charts/34/supplemental/language_plural_rules.html)" + }, + "theme.blog.tagTitle": { + "message": "{nPosts} 含有標籤「{tagName}」", + "description": "The title of the page for a blog tag" + }, + "theme.tags.tagsPageLink": { + "message": "檢視所有標籤", + "description": "The label of the link targeting the tag list page" + }, + "theme.colorToggle.ariaLabel": { + "message": "切換淺色/暗黑模式（當前為{mode}）", + "description": "The ARIA label for the navbar color mode toggle" + }, + "theme.colorToggle.ariaLabel.mode.dark": { + "message": "暗黑模式", + "description": "The name for the dark color mode" + }, + "theme.colorToggle.ariaLabel.mode.light": { + "message": "淺色模式", + "description": "The name for the light color mode" + }, + "theme.docs.breadcrumbs.navAriaLabel": { + "message": "頁面路徑", + "description": "The ARIA label for the breadcrumbs" + }, + "theme.docs.DocCard.categoryDescription.plurals": { + "message": "{count} 個項目", + "description": "The default description for a category card in the generated index about how many items this category includes" + }, + "theme.docs.paginator.navAriaLabel": { + "message": "文件選項卡", + "description": "The ARIA label for the docs pagination" + }, + "theme.docs.paginator.previous": { + "message": "上一頁", + "description": "The label used to navigate to the previous doc" + }, + "theme.docs.paginator.next": { + "message": "下一頁", + "description": "The label used to navigate to the next doc" + }, + "theme.docs.tagDocListPageTitle.nDocsTagged": { + "message": "{count} 篇文件帶有標籤", + "description": "Pluralized label for \"{count} docs tagged\". Use as much plural forms (separated by \"|\") as your language support (see https://www.unicode.org/cldr/cldr-aux/charts/34/supplemental/language_plural_rules.html)" + }, + "theme.docs.tagDocListPageTitle": { + "message": "{nDocsTagged}「{tagName}」", + "description": "The title of the page for a docs tag" + }, + "theme.docs.versionBadge.label": { + "message": "版本：{versionLabel}" + }, + "theme.docs.versions.unreleasedVersionLabel": { + "message": "此為 {siteTitle} {versionLabel} 版尚未發行的文件。", + "description": "The label used to tell the user that he's browsing an unreleased doc version" + }, + "theme.docs.versions.unmaintainedVersionLabel": { + "message": "此為 {siteTitle} {versionLabel} 版的文件，現已不再積極維護。", + "description": "The label used to tell the user that he's browsing an unmaintained doc version" + }, + "theme.docs.versions.latestVersionSuggestionLabel": { + "message": "最新的文件請參閱 {latestVersionLink} ({versionLabel})。", + "description": "The label used to tell the user to check the latest version" + }, + "theme.docs.versions.latestVersionLinkLabel": { + "message": "最新版本", + "description": "The label used for the latest version suggestion link label" + }, + "theme.common.editThisPage": { + "message": "編輯此頁", + "description": "The link label to edit the current page" + }, + "theme.common.headingLinkTitle": { + "message": "{heading}的直接連結", + "description": "Title for link to heading" + }, + "theme.lastUpdated.atDate": { + "message": "於 {date} ", + "description": "The words used to describe on which date a page has been last updated" + }, + "theme.lastUpdated.byUser": { + "message": "由 {user} ", + "description": "The words used to describe by who the page has been last updated" + }, + "theme.lastUpdated.lastUpdatedAtBy": { + "message": "最後{byUser}{atDate}更新", + "description": "The sentence used to display when a page has been last updated, and by who" + }, + "theme.navbar.mobileVersionsDropdown.label": { + "message": "選擇版本", + "description": "The label for the navbar versions dropdown on mobile view" + }, + "theme.NotFound.title": { + "message": "找不到頁面", + "description": "The title of the 404 page" + }, + "theme.tags.tagsListLabel": { + "message": "標籤：", + "description": "The label alongside a tag list" + }, + "theme.admonition.caution": { + "message": "警告", + "description": "The default label used for the Caution admonition (:::caution)" + }, + "theme.admonition.danger": { + "message": "危險", + "description": "The default label used for the Danger admonition (:::danger)" + }, + "theme.admonition.info": { + "message": "信息", + "description": "The default label used for the Info admonition (:::info)" + }, + "theme.admonition.note": { + "message": "備註", + "description": "The default label used for the Note admonition (:::note)" + }, + "theme.admonition.tip": { + "message": "提示", + "description": "The default label used for the Tip admonition (:::tip)" + }, + "theme.admonition.warning": { + "message": "warning", + "description": "The default label used for the Warning admonition (:::warning)" + }, + "theme.AnnouncementBar.closeButtonAriaLabel": { + "message": "關閉", + "description": "The ARIA label for close button of announcement bar" + }, + "theme.blog.sidebar.navAriaLabel": { + "message": "最近部落格文章導覽", + "description": "The ARIA label for recent posts in the blog sidebar" + }, + "theme.CodeBlock.copied": { + "message": "複製成功", + "description": "The copied button label on code blocks" + }, + "theme.CodeBlock.copyButtonAriaLabel": { + "message": "複製代碼至剪貼簿", + "description": "The ARIA label for copy code blocks button" + }, + "theme.CodeBlock.copy": { + "message": "複製", + "description": "The copy button label on code blocks" + }, + "theme.CodeBlock.wordWrapToggle": { + "message": "切換自動換行", + "description": "The title attribute for toggle word wrapping button of code block lines" + }, + "theme.DocSidebarItem.expandCategoryAriaLabel": { + "message": "Expand sidebar category '{label}'", + "description": "The ARIA label to expand the sidebar category" + }, + "theme.DocSidebarItem.collapseCategoryAriaLabel": { + "message": "Collapse sidebar category '{label}'", + "description": "The ARIA label to collapse the sidebar category" + }, + "theme.NavBar.navAriaLabel": { + "message": "主導航", + "description": "The ARIA label for the main navigation" + }, + "theme.navbar.mobileLanguageDropdown.label": { + "message": "選擇語言", + "description": "The label for the mobile language switcher dropdown" + }, + "theme.NotFound.p1": { + "message": "我們沒有您要找的頁面。", + "description": "The first paragraph of the 404 page" + }, + "theme.NotFound.p2": { + "message": "請聯絡原始連結來源網站的所有者，並通知他們連結已毀損。", + "description": "The 2nd paragraph of the 404 page" + }, + "theme.TOCCollapsible.toggleButtonLabel": { + "message": "本頁導覽", + "description": "The label used by the button on the collapsible TOC component" + }, + "theme.blog.post.readMore": { + "message": "閱讀更多", + "description": "The label used in blog post item excerpts to link to full blog posts" + }, + "theme.blog.post.readMoreLabel": { + "message": "閱讀 {title} 全文", + "description": "The ARIA label for the link to full blog posts from excerpts" + }, + "theme.blog.post.readingTime.plurals": { + "message": "閱讀時間約 {readingTime} 分鐘", + "description": "Pluralized label for \"{readingTime} min read\". Use as much plural forms (separated by \"|\") as your language support (see https://www.unicode.org/cldr/cldr-aux/charts/34/supplemental/language_plural_rules.html)" + }, + "theme.docs.breadcrumbs.home": { + "message": "主頁面", + "description": "The ARIA label for the home page in the breadcrumbs" + }, + "theme.docs.sidebar.collapseButtonTitle": { + "message": "收起側邊欄", + "description": "The title attribute for collapse button of doc sidebar" + }, + "theme.docs.sidebar.collapseButtonAriaLabel": { + "message": "收起側邊欄", + "description": "The title attribute for collapse button of doc sidebar" + }, + "theme.docs.sidebar.navAriaLabel": { + "message": "文件側邊欄", + "description": "The ARIA label for the sidebar navigation" + }, + "theme.docs.sidebar.closeSidebarButtonAriaLabel": { + "message": "Close navigation bar", + "description": "The ARIA label for close button of mobile sidebar" + }, + "theme.docs.sidebar.toggleSidebarButtonAriaLabel": { + "message": "Toggle navigation bar", + "description": "The ARIA label for hamburger menu button of mobile navigation" + }, + "theme.navbar.mobileSidebarSecondaryMenu.backButtonLabel": { + "message": "← 回到主選單", + "description": "The label of the back button to return to main menu, inside the mobile navbar sidebar secondary menu (notably used to display the docs sidebar)" + }, + "theme.docs.sidebar.expandButtonTitle": { + "message": "展開側邊欄", + "description": "The ARIA label and title attribute for expand button of doc sidebar" + }, + "theme.docs.sidebar.expandButtonAriaLabel": { + "message": "展開側邊欄", + "description": "The ARIA label and title attribute for expand button of doc sidebar" + }, + "cmfcmf/d-s-l.searchBar.placeholder": { + "message": "搜索...", + "description": "Placeholder shown in the searchbar" + }, + "cmfcmf/d-s-l.searchBar.clearButtonTitle": { + "message": "清除", + "description": "Title of the button to clear the current search input" + }, + "cmfcmf/d-s-l.searchBar.detachedCancelButtonText": { + "message": "取消", + "description": "Text of the button to close the detached search window" + }, + "cmfcmf/d-s-l.searchBar.submitButtonTitle": { + "message": "搜索", + "description": "Title of the button to submit a new search" + }, + "cmfcmf/d-s-l.searchBar.noResults": { + "message": "无搜索结果", + "description": "message shown if no results are found" + }, + "theme.ErrorPageContent.tryAgain": { + "message": "重試", + "description": "The label of the button to try again rendering when the React error boundary captures an error" + }, + "theme.common.skipToMainContent": { + "message": "跳至主要内容", + "description": "The skip to content label used for accessibility, allowing to rapidly navigate to main content with keyboard tab/enter navigation" + }, + "theme.tags.tagsPageTitle": { + "message": "標籤", + "description": "The title of the tag list page" + }, + "theme.unlistedContent.title": { + "message": "未列出頁", + "description": "The unlisted content banner title" + }, + "theme.unlistedContent.message": { + "message": "此頁面未列出。搜索引擎不會對其索引，只有擁有直接連結的用戶才能訪問。", + "description": "The unlisted content banner message" + } +} diff --git a/docs/i18n/zh-Hant/docusaurus-theme-classic/footer.json b/docs/i18n/zh-Hant/docusaurus-theme-classic/footer.json new file mode 100644 index 0000000..079de66 --- /dev/null +++ b/docs/i18n/zh-Hant/docusaurus-theme-classic/footer.json @@ -0,0 +1,50 @@ +{ + "link.title.PHP API Docs": { + "message": "PHP API 文檔", + "description": "The title of the footer links column with title=PHP API Docs in the footer" + }, + "link.title.Official Resources": { + "message": "官方資源", + "description": "The title of the footer links column with title=Official Resources in the footer" + }, + "link.title.Christian Flach": { + "message": "Christian Flach", + "description": "The title of the footer links column with title=Christian Flach in the footer" + }, + "link.item.label.Getting Started": { + "message": "入門指南", + "description": "The label of footer link with label=Getting Started linking to docs/getting-started" + }, + "link.item.label.API Key": { + "message": "API 金鑰", + "description": "The label of footer link with label=API Key linking to docs/api-key" + }, + "link.item.label.Usage": { + "message": "使用方式", + "description": "The label of footer link with label=Usage linking to docs/usage" + }, + "link.item.label.Introduction Guide": { + "message": "介紹指南", + "description": "The label of footer link with label=Introduction Guide linking to https://openweathermap.org/guide" + }, + "link.item.label.Pricing": { + "message": "價格", + "description": "The label of footer link with label=Pricing linking to https://openweathermap.org/price" + }, + "link.item.label.GitHub": { + "message": "GitHub", + "description": "The label of footer link with label=GitHub linking to https://github.com/cmfcmf" + }, + "link.item.label.Twitter": { + "message": "X", + "description": "The label of footer link with label=Twitter linking to https://twitter.com/christianmflach" + }, + "link.item.label.Privacy / Datenschutz": { + "message": "隱私政策", + "description": "The label of footer link with label=Privacy / Datenschutz linking to https://cmfcmf.github.io/about" + }, + "copyright": { + "message": "版權所有 © 2024 Christian Flach.\n 此專案與 OpenWeatherMap 無關。", + "description": "The footer copyright" + } +} diff --git a/docs/i18n/zh-Hant/docusaurus-theme-classic/navbar.json b/docs/i18n/zh-Hant/docusaurus-theme-classic/navbar.json new file mode 100644 index 0000000..cb3541c --- /dev/null +++ b/docs/i18n/zh-Hant/docusaurus-theme-classic/navbar.json @@ -0,0 +1,18 @@ +{ + "title": { + "message": "OpenWeatherMap PHP API", + "description": "The title in the navbar" + }, + "logo.alt": { + "message": "Sun Logo", + "description": "The alt text of navbar logo" + }, + "item.label.Docs": { + "message": "文檔", + "description": "Navbar item with label Docs" + }, + "item.label.GitHub": { + "message": "GitHub", + "description": "Navbar item with label GitHub" + } +} From 8fcfaeda1c21532a16f66e771f4e626281ae1172 Mon Sep 17 00:00:00 2001 From: Elvis Mao Date: Wed, 7 Aug 2024 23:22:40 +0800 Subject: [PATCH 3/5] Chinese Translation --- .../current/apis/weather-forecast.md | 109 ++++++++++++++++++ .../current/getting-started.md | 51 ++++++++ 2 files changed, 160 insertions(+) create mode 100644 docs/i18n/zh-Hant/docusaurus-plugin-content-docs/current/apis/weather-forecast.md create mode 100644 docs/i18n/zh-Hant/docusaurus-plugin-content-docs/current/getting-started.md diff --git a/docs/i18n/zh-Hant/docusaurus-plugin-content-docs/current/apis/weather-forecast.md b/docs/i18n/zh-Hant/docusaurus-plugin-content-docs/current/apis/weather-forecast.md new file mode 100644 index 0000000..a3100e4 --- /dev/null +++ b/docs/i18n/zh-Hant/docusaurus-plugin-content-docs/current/apis/weather-forecast.md @@ -0,0 +1,109 @@ +--- +title: 天氣預報 API +sidebar_label: '天氣預報' +--- + +此 API 允許您檢索 16 天/每日和 5 天/3 小時的天氣預報。 + +> 對應的 OpenWeatherMap 文件： +> - [5 天/3 小時預報](https://openweathermap.org/forecast5) +> - [16 天/每日預報](https://openweathermap.org/forecast16) + +`$owm->getWeatherForecast()` 函式接受以下參數： + +| 名稱 | 類型 | 預設值 | 描述 | +|------|------|---------|-------------| +| `$query` | `mixed` | -- | 見下文 | +| `$units` | `"imperial"`|`"metric"` | `"imperial"` | 使用的單位 | +| `$lang` | `string` | `en` | [官方文件](https://openweathermap.org/forecast16#multi)底部列出語言之一 | +| `$appid` | `string` | `''` | 已棄用，始終設置為 `''` | +| `$days` | `int` (1 - 16) | `1` | 要檢索預報的天數。如果 `$days` 在 1 到 5 之間，則使用 5 天/3 小時預報 API。如果 `$days` 在 6 到 16 之間，則使用 16 天/每日預報 API。| + +如果您希望在有 3 小時預報時檢索每日預報，可以使用 `->getDailyWeatherForecast()`。 + +## `$query` 參數 + +第一個參數確定要獲取天氣數據的位置。有幾種可能的函式： + +### 根據城市名稱 + +指定國家是可選的。 + +```php +$forecasts = $owm->getWeatherForecast('Berlin,DE', $units, $lang, '', $days); +``` + +### 根據城市 ID + +一個城市 ID： +```php +$forecasts = $owm->getWeatherForecast(2172797, $units, $lang, '', $days); +``` + +### 根據郵政編碼 + +指定國家是可選的。 + +```php +// 印度，海得拉巴 +$forecasts = $owm->getWeatherForecast('zip:500001,IN', $units, $lang, '', $days); +``` + +### 根據座標 + +```php +$forecasts = $owm->getWeatherForecast(['lat' => 77.73038, 'lon' => 41.89604], + $units, $lang, '', $days); +``` + +## `$forecasts` 物件 + +`$forecasts` 是 `Cmfcmf\OpenWeatherMap\WeatherForecast` 的實例。它提供以下數據： + +| 名稱 | 類型 | 描述 | +|------|------|-------------| +| `lastUpdate` | `\ḐateTimeInterface` | 數據的最後更新時間 | +| `city->id` | `int` | 內部城市 ID | +| `city->name` | `string` | 城市名稱 | +| `city->country` | `string` | 城市國家代碼 | +| `city->timezone` | `\DateTimeZone`|`null` | 城市時區 | +| `city->lon` | `float` | 城市經度 | +| `city->lat` | `float` | 城市緯度 | + +要檢索預報，請迭代該對象： + +```php +foreach ($forecasts as $forecast) { + // 執行操作 +} +``` + +### `$forecast` 物件 + +`$forecast` 是 `Cmfcmf\OpenWeatherMap\Forecast` 的實例，繼承自 `Cmfcmf\OpenWeatherMap\CurrentWeather` 對象。 + +| 名稱 | 類型 | 描述 | +|------|------|-------------| +| `time->day` | `\DateTimeInterface` | 預報日期 | +| `time->from` | `\DateTimeInterface` | 預報的確切開始時間。對於 16 天/每日預報，這對應於 `time->day`。對於 5 天/3 小時預報，它對應於 3 小時窗口的開始。| +| `time->to` | `\DateTimeInterface` | 預報的確切結束時間。對於 16 天/每日預報，這對應於 `time->day` 的 `23:59:59`。對於 5 天/3 小時預報，它對應於 3 小時窗口的結束。| +| `...` | `...` | `CurrentWeather` 對象的所有其他屬性，如[此處](current-weather.md#weather-object)所述。| + +### 僅適用於 5 天/3 小時預報 + +| 名稱 | 類型 | 描述 | +|------|------|-------------| +| `temperature->now` | `Unit` | 注意：這應該命名為 `temperature->avg`，僅因向後兼容性而命名為 `temperature->now`！返回給定位置的平均溫度（例如，大城市可能有多個溫度測量站） | +| `temperature->min` | `Unit` | 給定位置的最低溫度 | +| `temperature->max` | `Unit` | 給定位置的最高溫度 | + +### 僅適用於 16 天/每日預報 + +| 名稱 | 類型 | 描述 | +|------|------|-------------| +| `temperature->morning` | `Unit` | 早晨的溫度 | +| `temperature->now` | `Unit` | 白天的溫度 | +| `temperature->evening` | `Unit` | 晚上的溫度 | +| `temperature->night` | `Unit` | 夜晚的溫度 | +| `temperature->min` | `Unit` | 白天的最低溫度 | +| `temperature->max` | `Unit` | 白天的最高溫度 | diff --git a/docs/i18n/zh-Hant/docusaurus-plugin-content-docs/current/getting-started.md b/docs/i18n/zh-Hant/docusaurus-plugin-content-docs/current/getting-started.md new file mode 100644 index 0000000..9fc75b0 --- /dev/null +++ b/docs/i18n/zh-Hant/docusaurus-plugin-content-docs/current/getting-started.md @@ -0,0 +1,51 @@ +--- +title: 入門指南 +--- + +*OpenWeatherMap PHP API* 是 [OpenWeatherMap.org](http://www.OpenWeatherMap.org) 天氣 API 的 PHP 客戶端。 + +此項目旨在統一提供的數據並消除不一致性。它 **不是** 由 OpenWeatherMap 維護，也 **不是** 官方的 API 包裝器。 + +請注意，僅支持以下 API： + +- [當前天氣數據](apis/current-weather.md) +- [16 天/每日和 5 天/每 3 小時預報](apis/weather-forecast.md) +- [空氣污染（CO、O3、SO2、NO2）](apis/air-pollution.md) +- [紫外線指數](apis/uv-index.md) + +> 我對於添加支持 OpenWeatherMap 其他 API 的請求持開放態度，只要它們不需要付費訂閱。因為我無法自行支付測試付費 API 的費用。 + +## PHP 要求 + +- **PHP 7.1 及更高版本（包括 PHP 8）**（如果您仍在使用 PHP 5.x，您必須使用此庫的 2.x 版本） +- PHP json 擴展 +- PHP libxml 擴展 +- PHP simplexml 擴展 + +## 安裝 + +此項目可在 [Packagist](https://packagist.org/packages/cmfcmf/openweathermap-php-api) 上找到，最佳安裝方式是使用 [Composer](http://getcomposer.org)： + +```bash +composer require "cmfcmf/openweathermap-php-api" +``` + +### 所需的 PSR-17/-18 依賴項 + +您還需要安裝兩個附加的依賴項： + +1. 一個 [PSR-17](https://www.php-fig.org/psr/psr-17/) 兼容的 HTTP 工廠實現。 +2. 一個 [PSR-18](https://www.php-fig.org/psr/psr-18/) 兼容的 HTTP 客戶端實現。 + +如果您將此項目集成到 PHP 框架中，它很可能已經包含了這些依賴項。 +否則，請瀏覽 Packagist 上的實現列表，選擇適合您項目的實現： + +- [PSR-17 兼容實現列表](https://packagist.org/providers/psr/http-factory-implementation) +- [PSR-18 兼容實現列表](https://packagist.org/providers/psr/http-client-implementation) + +如果您不知道選擇哪個，請嘗試以下命令： + +```bash +composer require "http-interop/http-factory-guzzle:^1.0" \ + "php-http/guzzle6-adapter:^2.0 || ^1.0" +``` \ No newline at end of file From 5e3afe7530c41bd7a746597e5643ccfe56a5ef01 Mon Sep 17 00:00:00 2001 From: Elvis Mao Date: Wed, 7 Aug 2024 23:23:08 +0800 Subject: [PATCH 4/5] Chinese Translation --- .../current/apis/uv-index.md | 63 ++++++++++ .../current/usage.md | 116 ++++++++++++++++++ 2 files changed, 179 insertions(+) create mode 100644 docs/i18n/zh-Hant/docusaurus-plugin-content-docs/current/apis/uv-index.md create mode 100644 docs/i18n/zh-Hant/docusaurus-plugin-content-docs/current/usage.md diff --git a/docs/i18n/zh-Hant/docusaurus-plugin-content-docs/current/apis/uv-index.md b/docs/i18n/zh-Hant/docusaurus-plugin-content-docs/current/apis/uv-index.md new file mode 100644 index 0000000..9b571d4 --- /dev/null +++ b/docs/i18n/zh-Hant/docusaurus-plugin-content-docs/current/apis/uv-index.md @@ -0,0 +1,63 @@ +--- +title: 紫外線指數 API +sidebar_label: '紫外線指數' +--- + +此 API 允許您檢索當前、預測和歷史的紫外線指數（UV 指數）。 + +> [對應的 OpenWeatherMap 文件](https://openweathermap.org/api/uvi) + +## 當前紫外線指數 + +您可以通過緯度和經度檢索當前的紫外線指數。響應包括時間、位置和 UV 指數值。 + +```php +$uvIndex = $owm->getCurrentUVIndex($lat, $lon); +``` + +### 範例 + +獲取柏林的當前紫外線指數。 + +```php +$uvIndex = $owm->getCurrentUVIndex(52.520008, 13.404954); +echo "當前紫外線指數：$uvIndex->uvIndex"; +``` + +## 預測紫外線指數 + +您可以檢索最多 8 天的紫外線指數預測。返回值是一個 `UVIndex` 對象的數組。 + +```php +$uvForecast = $owm->getForecastUVIndex($lat, $lon, $cnt = 8) +``` + +### 範例 + +```php +$forecast = $owm->getForecastUVIndex(52.520008, 13.404954); +foreach ($forecast as $day) { + echo "{$day->time->format('r')} 的紫外線指數將為：$day->uvIndex"; +} +``` + +## 歷史紫外線指數 + +您可以檢索從 2017 年 6 月開始的每日歷史紫外線指數數據。 + +```php +$history = $owm->getHistoricUVIndex($lat, $lon, $from, $to); +``` + +### 範例 + +檢索柏林四個月前的一個月歷史紫外線數據。 + +```php +$history = $owm->getHistoricUVIndex(52.520008, 13.404954, + new DateTime('-4month'), + new DateTime('-3month')); +foreach ($history as $day) { + echo "{$day->time->format('r')} 的紫外線指數為：$day->uvIndex"; +} +``` \ No newline at end of file diff --git a/docs/i18n/zh-Hant/docusaurus-plugin-content-docs/current/usage.md b/docs/i18n/zh-Hant/docusaurus-plugin-content-docs/current/usage.md new file mode 100644 index 0000000..43fdc0f --- /dev/null +++ b/docs/i18n/zh-Hant/docusaurus-plugin-content-docs/current/usage.md @@ -0,0 +1,116 @@ +--- +title: 使用說明 +--- + +所有 API 都可以通過 `Cmfcmf\OpenWeatherMap` 對象訪問。 +要構建此對象，您需要提供您的 API 密鑰、兼容 PSR-18 的 HTTP 客戶端和兼容 PSR-17 的 HTTP 請求工廠： + +```php +use Cmfcmf\OpenWeatherMap; + +$owm = new OpenWeatherMap('YOUR-API-KEY', $httpClient, $httpRequestFactory); +``` + +> **注意：** 從現在起，我們將把 `Cmfcmf\OpenWeatherMap` 的實例稱為 `$owm`。 + +## 示例 + +```php +getWeather('Berlin', 'metric', 'de'); +} catch(OWMException $e) { + echo 'OpenWeatherMap 異常：' . $e->getMessage() . '（代碼 ' . $e->getCode() . '）。'; +} catch(\Exception $e) { + echo '一般異常：' . $e->getMessage() . '（代碼 ' . $e->getCode() . '）。'; +} + +echo $weather->temperature; +``` + +## `Unit` 對象 + +大多數值如溫度、降水量等，均以 `Cmfcmf\OpenWeatherMap\Util\Unit` 類的實例返回。這些對象提供了以下信息： +數值（例如，`26.9`），單位（例如，`°C`），以及有時候的描述（例如，`大雨`）。 +為了使這一點更清楚，我們來看一個具體的例子： + +```php +$weather = $owm->getWeather('Berlin', 'metric'); +// @var Cmfcmf\OpenWeatherMap\Util\Unit $temperature +$temperature = $weather->temperature->now; + +$temperature->getValue(); // 26.9 +$temperature->getUnit(); // "°C" +$temperature->getDescription(); // "" +$temperature->getFormatted(); // "26.9 °C" +$temperature->__toString(); // "26.9 °C" +``` + +## 請求緩存 + +您可以通過提供 [PSR-6 兼容](https://www.php-fig.org/psr/psr-6/) 的緩存作為第四個構造參數以及生存時間作為第五個參數來自動緩存請求： + +```php +use Cmfcmf\OpenWeatherMap; + +// 緩存時間以秒為單位，默認為 600 秒（10 分鐘）。 +$ttl = 600; + +$owm = new OpenWeatherMap('YOUR-API-KEY', $httpClient, $httpRequestFactory, + $cache, $ttl); +``` + +您可以通過調用 `->wasCached()` 檢查上次請求是否已緩存： + +```php +$owm->getRawWeatherData('Berlin'); + +if ($owm->wasCached()) { + echo "上次請求已緩存"; +} else { + echo "上次請求未緩存"; +} +``` + +## 異常處理 + +確保適當處理異常。 +每當 OpenWeatherMap API 返回異常時，它將被轉換為 `Cmfcmf\OpenWeatherMap\Exception` 的實例。 +作為特殊情況，如果找不到您查詢的城市/位置/坐標，API 會拋出 `Cmfcmf\OpenWeatherMap\NotFoundException`。該異常繼承自 `Cmfcmf\OpenWeatherMap\Exception`。 + +如果發生其他錯誤，將拋出繼承自 `\Exception` 的異常。 + +```php +use Cmfcmf\OpenWeatherMap\Exception as OWMException; +use Cmfcmf\OpenWeatherMap\NotFoundException as OWMNotFoundException; + +try { + $weather = $owm->getWeather('Berlin'); +} catch (OWMNotFoundException $e) { + // TODO: 處理“未找到城市”異常 + // 您可以選擇跳過 `OWM的處理程序，因為它繼承自 `OWMException`。 +} catch (OWMException $e) { + // TODO: 處理 API 異常 +} catch (\Exception $e) { + // TODO: 處理一般異常 +} +``` + +這樣可以確保您的代碼能夠正確的處理不同類型的異常，並且可以根據不同的情況採取適當的行動。例如，您可以選擇記錄異常、重試請求或向用戶顯示錯誤消息。 + +通過這些基本的使用說明，您應該能夠開始使用 OpenWeatherMap PHP API 來獲取天氣數據並將其集成到您的應用程式中。確保遵循 OpenWeatherMap 的使用條款並正確處理所有潛在的異常情況，以確保您的應用程序穩定運行。 \ No newline at end of file From 714fe896969c967cdc3e06e40dec0dff9ab700b5 Mon Sep 17 00:00:00 2001 From: Elvis Mao Date: Wed, 7 Aug 2024 23:24:17 +0800 Subject: [PATCH 5/5] Chinese Translation --- .../current/apis/air-pollution.md | 80 ++++++++ .../current/apis/current-weather.md | 181 ++++++++++++++++++ 2 files changed, 261 insertions(+) create mode 100644 docs/i18n/zh-Hant/docusaurus-plugin-content-docs/current/apis/air-pollution.md create mode 100644 docs/i18n/zh-Hant/docusaurus-plugin-content-docs/current/apis/current-weather.md diff --git a/docs/i18n/zh-Hant/docusaurus-plugin-content-docs/current/apis/air-pollution.md b/docs/i18n/zh-Hant/docusaurus-plugin-content-docs/current/apis/air-pollution.md new file mode 100644 index 0000000..883084a --- /dev/null +++ b/docs/i18n/zh-Hant/docusaurus-plugin-content-docs/current/apis/air-pollution.md @@ -0,0 +1,80 @@ +--- +title: 空氣污染 API +sidebar_label: '空氣污染' +--- + +此 API 允許您檢索當前、預測和歷史的紫外線指數（UV 指數）。 + +> 對應的 OpenWeatherMap 文件： +> +> - [一氧化碳 (CO)](https://openweathermap.org/api/pollution/co) +> - [臭氧 (O3)](https://openweathermap.org/api/pollution/o3) +> - [二氧化氮 (NO2)](https://openweathermap.org/api/pollution/no2) +> - [二氧化硫 (SO2)](https://openweathermap.org/api/pollution/so2) + +## 用法 + +- `$type`：可以是 `"O3"`、`"NO2"`、`"SO2"` 或 `"CO"` 其中之一。 +- `$lat` / `$lng`：緯度和經度必須以字符串形式提供，因為小數點後的位數決定了搜索半徑。指定更多位數會導致更精確的結果，但位數過多可能導致無法獲取結果。 +- `$date`：要檢索數據的日期。`"current"` 請求最新可用的信息。您也可以以 ISO 8601 格式指定日期。更多信息請參見 [OpenWeatherMap 文件](https://openweathermap.org/api/pollution/co)。 + +```php +// $type = +$co = $owm->getAirPollution($type, $lat, $lng, $date = "current"); +``` + +返回值取決於 `$type`，在後續部分進行討論。 + +## 一氧化碳 (CO) + +```php +$co = $owm->getAirPollution("CO", "52", "13"); +if ($co === null) { + // 無可用數據 +} else { + foreach ($co->values as $data) { + echo $data["value"]; + echo $data["value"]->getPrecision(); + echo $data["pressure"]; + } +} +``` + +## 臭氧 (O3) + +```php +$o3 = $owm->getAirPollution("O3", "52", "13"); +if ($o3 === null) { + // 無可用數據 +} else { + echo $o3->value; +} +``` + +## 二氧化氮 (NO2) + +```php +$no2 = $owm->getAirPollution("NO2", "52", "13"); +if ($no2 === null) { + // 無可用數據 +} else { + echo $no2->value; + echo $no2->valueStratosphere; + echo $no2->valueTroposphere; +} +``` + +## 二氧化硫 (SO2) + +```php +$so2 = $owm->getAirPollution("SO2", "52", "13"); +if ($so2 === null) { + // 無可用數據 +} else { + foreach ($so2->values as $data) { + echo $data["value"]; + echo $data["value"]->getPrecision(); + echo $data["pressure"]; + } +} +``` \ No newline at end of file diff --git a/docs/i18n/zh-Hant/docusaurus-plugin-content-docs/current/apis/current-weather.md b/docs/i18n/zh-Hant/docusaurus-plugin-content-docs/current/apis/current-weather.md new file mode 100644 index 0000000..9e74ad9 --- /dev/null +++ b/docs/i18n/zh-Hant/docusaurus-plugin-content-docs/current/apis/current-weather.md @@ -0,0 +1,181 @@ +--- +title: 當前天氣 API +sidebar_label: '當前天氣' +--- + +此 API 允許您檢索當前的天氣數據。 + +> [對應的 OpenWeatherMap 文件](https://openweathermap.org/current) + +`$owm->getWeather()` 函式接受以下參數： + +| 名稱 | 類型 | 預設值 | 描述 | +|------|------|---------|-------------| +| `$query` | `mixed` | -- | 請參見下文 | +| `$units` | `"imperial"`|`"metric"` | `"imperial"` | 使用的單位 | +| `$lang` | `string` | `en` | 語言之一，請參見 [官方文件底部](https://openweathermap.org/current#multi) | + +## `$query` 參數 + +第一個參數確定要獲取天氣數據的位置。有多種函式可用： + +### 根據城市名稱 + +指定國家是可選的。 + +```php +$weather = $owm->getWeather('Berlin,DE', $units, $lang); +``` + +### 根據城市 ID + +單個城市 ID： +```php +$weather = $owm->getWeather(2172797, $units, $lang); +``` + +多個城市 ID： +```php +// 警告：這使用了一個不同的函式 (getWeatherGroup) +// 與其他查詢格式 (getWeather) 不同！ +$weathers = $owm->getWeatherGroup([2172797, 2172798], $units, $lang); +foreach ($weathers as $weather) { + // 處理 +} +``` + +### 根據郵政編碼 + +指定國家是可選的。 + +```php +// 印度，海得拉巴 +$weather = $owm->getWeather('zip:500001,IN', $units, $lang); +``` + +### 根據座標 + +```php +$weather = $owm->getWeather(['lat' => 77.73038, 'lon' => 41.89604], + $units, $lang); +``` + +## `$weather` 對象 + +返回的對象是一個 `Cmfcmf\OpenWeatherMap\CurrentWeather` 實例。它提供以下數據： + +| 名稱 | 類型 | 描述 | +|------|------|-------------| +| `lastUpdate` | `\DateTimeInterface` | 數據的最後更新時間 | +| `temperature->now` | `Unit` | 注意：這應命名為 `temperature->avg`，僅為向後兼容而命名為 `temperature->now`！返回給定位置的當前平均溫度（例如，一個大城市可能有多個溫度測量站） | +| `temperature->min` | `Unit` | 給定位置的當前最低溫度 | +| `temperature->max` | `Unit` | 給定位置的當前最高溫度 | +| `pressure` | `Unit` | 氣壓 | +| `humidity` | `Unit` | 濕度 | +| `sun->rise` | `\DateTimeInterface` | 日出時間 | +| `sun->set` | `\DateTimeInterface` | 日落時間 | +| `wind->speed` | `Unit` | 風速 | +| `wind->direction` | `Unit` | 風向 | +| `clouds` | `Unit` | 雲量百分比 | +| `precipitation` | `Unit` | 最近的降水 | +| `weather->id` | `int` | 當前天氣現象 ID | +| `weather->description` | `string` | 當前天氣描述 | +| `weather->icon` | `string` | 當前天氣圖標名稱。使用 `weather->getIconUrl()` 獲取 OpenWeatherMap 圖標的 URL | +| `city->id` | `int` | 內部城市 ID | +| `city->name` | `string` | 城市名稱 | +| `city->country` | `string` | 城市國家代碼 | +| `city->timezone` | `\DateTimeZone`|`null` | 城市時區 | +| `city->lon` | `float` | 城市經度 | +| `city->lat` | `float` | 城市緯度 | + +## 獲取原始數據 + +### HTML + +您還可以請求以 HTML 頁面形式的數據： + +```php +$html = $owm->getRawWeatherData('Berlin', $units, $lang, null, 'html'); +``` + +結果： + +```html + + + + + + + + + + + +
Berlin
+
+
+
+ title +
+
+
12.73°C
+
+
+
+
雲量：89%
+
濕度：62%
+
風速：6.2 m/s
+
氣壓：1014hpa
+
+
+ 更多.. +
+ + + +``` + +### JSON + +```php +$json = $owm->getRawWeatherData('Berlin', 'metric', 'de', null, 'json'); +``` +結果： + +```json +{ + "coord":{"lon":13.41,"lat":52.52}, + "weather":[{"id":804,"main":"Clouds","description":"Bedeckt","icon":"04d"}], + "base":"stations", + "main":{"temp":12.73,"feels_like":7.4,"temp_min":11.67, + "temp_max":13.89,"pressure":1014,"humidity":62}, + "visibility":10000, + "wind":{"speed":6.2,"deg":200}, + "clouds":{"all":89}, + "dt":1579089181, + "sys":{"type":1,"id":1275,"country":"DE","sunrise":1579072219,"sunset":1579101619}, + "timezone":3600, + "id":2950159, + "name":"Berlin", + "cod":200 +} +``` + +### XML + +```php +$xml = $owm->getRawWeatherData('Berlin', 'metric', 'de', null, 'xml'); +``` + +結果： + +```xml + +DE3600 +``` \ No newline at end of file