From zsj950618 at gmail.com Fri May 4 14:13:45 2018 From: zsj950618 at gmail.com (Shengjing Zhu) Date: Fri, 04 May 2018 18:13:45 +0000 Subject: [Doc-SIG] Translating sample programs in documentation Message-ID: Sorry I just joined this list, maybe I lost the mail thread index. Since I have private email with Xuan about d.p.o Chinese translation, and he mentions translating code blocks and this thread on doc-sig, I'd like to reply publicly on list. > My point of view is we should not translate them, as we dont want to see ` ``for ? in ??:` pushed by anyone (I mean : we're writing code in english, even if the doc is translated we *still* have to write the code in english). Also, we have enough work translating the text, we don't need more. +1 I'd be strongly against translating variable names(identifier) to any language other than English. We write code in English, we share code around world. To write code in Chinese doesn't make any sense, only prevent other people reading the code. BTW, I joined the transifex Chinese team, and started to translate, let's make it meet the pep545 requirement first. And setup a temporary site to preview the result, https://zhsj.github.io/python-docs-zh-cn/ -- Regards, Shengjing Zhu From anthony.p.shaw at gmail.com Fri May 4 18:40:48 2018 From: anthony.p.shaw at gmail.com (anthony shaw) Date: Fri, 04 May 2018 22:40:48 +0000 Subject: [Doc-SIG] Video content in the standard library documentation Message-ID: Hi I spend a lot of time reading the standard library documentation pages and then condensing them down into small videos as part of either commercial instructional courses or internal training. The problem is that all this work is isn?t much help to the PSF or the wider community. It?s my view that many people can sit and read the reference pages when they really need to check function or class documentation but beginners can find the pages stifling, with lots of new words, phrases and references to other stdlib modules. I was thinking of providing a set of templates and guidelines for having ?5 minute overview? videos at the top of each standard library page. Videos would be embedded in the existing docs, starting with 3.7. Videos would first explain - why this module exists? What problem is it solving - core concepts and ideas - most basic usage examples with demos - where to find more information and other related modules Because modules change between minor versions, videos should not be a comprehensive guide to the module, but a starter guide for people unfamiliar with the module. The template, standards and guidelines for the creation of these video clips would live in the PSF documentation domain, as well as the review checklist and guidelines for adding them. Because many people would end up authoring the videos, consistency would be important, so a structured format and template is critical. I?m happy to volunteer to help create the template and guidelines. I know lots of teachers in the Python world who (hopefully) could start to contribute videos as well. Regards Anthony Shaw -------------- next part -------------- An HTML attachment was scrubbed... URL: From al at inventwithpython.com Sat May 5 21:55:34 2018 From: al at inventwithpython.com (Al Sweigart) Date: Sat, 5 May 2018 18:55:34 -0700 Subject: [Doc-SIG] Video content in the standard library documentation In-Reply-To: References: Message-ID: This is something I'd be interested in contributing to as well, if we could lock down a good template and guidelines for them. I created something similar for Scratch in a series of videos called "Scratch Blocks in 60 Seconds": https://www.youtube.com/watch?v=ZCVb_EKTwQM&list=PL0-84-yl1fUki_zQ1ouwGN8t3spCTLnpS On Fri, May 4, 2018 at 3:40 PM, anthony shaw wrote: > Hi > > I spend a lot of time reading the standard library documentation pages and > then condensing them down into small videos as part of either commercial > instructional courses or internal training. > > The problem is that all this work is isn?t much help to the PSF or the > wider community. > > It?s my view that many people can sit and read the reference pages when > they really need to check function or class documentation but beginners can > find the pages stifling, with lots of new words, phrases and references to > other stdlib modules. > > I was thinking of providing a set of templates and guidelines for having > ?5 minute overview? videos at the top of each standard library page. Videos > would be embedded in the existing docs, starting with 3.7. > > Videos would first explain > - why this module exists? What problem is it solving > - core concepts and ideas > - most basic usage examples with demos > - where to find more information and other related modules > > Because modules change between minor versions, videos should not be a > comprehensive guide to the module, but a starter guide for people > unfamiliar with the module. > > The template, standards and guidelines for the creation of these video > clips would live in the PSF documentation domain, as well as the review > checklist and guidelines for adding them. > > Because many people would end up authoring the videos, consistency would > be important, so a structured format and template is critical. > > I?m happy to volunteer to help create the template and guidelines. I know > lots of teachers in the Python world who (hopefully) could start to > contribute videos as well. > > Regards > Anthony Shaw > > _______________________________________________ > Doc-SIG maillist - Doc-SIG at python.org > https://mail.python.org/mailman/listinfo/doc-sig > > -------------- next part -------------- An HTML attachment was scrubbed... URL: From anthony.p.shaw at gmail.com Sat May 5 22:02:44 2018 From: anthony.p.shaw at gmail.com (anthony shaw) Date: Sun, 06 May 2018 02:02:44 +0000 Subject: [Doc-SIG] Video content in the standard library documentation In-Reply-To: References: Message-ID: Thanks Al! If you?re coming to PyCon next week I was thinking of doing a sprint on it for Monday or at least discussing it over the weekend. It?ll be difficult to get good audio of course, but I think I could write a standard specification in a day with enough people to discuss and collaborate On Sun, 6 May 2018 at 11:56 am, Al Sweigart wrote: > This is something I'd be interested in contributing to as well, if we > could lock down a good template and guidelines for them. I created > something similar for Scratch in a series of videos called "Scratch Blocks > in 60 Seconds": > https://www.youtube.com/watch?v=ZCVb_EKTwQM&list=PL0-84-yl1fUki_zQ1ouwGN8t3spCTLnpS > > On Fri, May 4, 2018 at 3:40 PM, anthony shaw > wrote: > >> Hi >> >> I spend a lot of time reading the standard library documentation pages >> and then condensing them down into small videos as part of either >> commercial instructional courses or internal training. >> >> The problem is that all this work is isn?t much help to the PSF or the >> wider community. >> >> It?s my view that many people can sit and read the reference pages when >> they really need to check function or class documentation but beginners can >> find the pages stifling, with lots of new words, phrases and references to >> other stdlib modules. >> >> I was thinking of providing a set of templates and guidelines for having >> ?5 minute overview? videos at the top of each standard library page. Videos >> would be embedded in the existing docs, starting with 3.7. >> >> Videos would first explain >> - why this module exists? What problem is it solving >> - core concepts and ideas >> - most basic usage examples with demos >> - where to find more information and other related modules >> >> Because modules change between minor versions, videos should not be a >> comprehensive guide to the module, but a starter guide for people >> unfamiliar with the module. >> >> The template, standards and guidelines for the creation of these video >> clips would live in the PSF documentation domain, as well as the review >> checklist and guidelines for adding them. >> >> Because many people would end up authoring the videos, consistency would >> be important, so a structured format and template is critical. >> >> I?m happy to volunteer to help create the template and guidelines. I know >> lots of teachers in the Python world who (hopefully) could start to >> contribute videos as well. >> >> Regards >> Anthony Shaw >> >> _______________________________________________ >> Doc-SIG maillist - Doc-SIG at python.org >> https://mail.python.org/mailman/listinfo/doc-sig >> >> > -------------- next part -------------- An HTML attachment was scrubbed... URL: From julien at palard.fr Sun May 6 04:25:20 2018 From: julien at palard.fr (Julien Palard) Date: Sun, 06 May 2018 04:25:20 -0400 Subject: [Doc-SIG] Video content in the standard library documentation In-Reply-To: References: Message-ID: > I was thinking of providing a set of templates and guidelines for having ?5 minute overview? videos I propose this guideline: - Never show the face of someone speaking. Why? It allows to: - FIX a section of the sound track without re-recording the video track (in case of a error, or to better phrase something). - Translate the audio tracks of the videos without caring about lip sync (I suspect non of us are willing to do lip sync). Why fixing is important? I know one (but won't public-shame) of a really great Python video, really high video, studio, setup quality, video editing, ... all good, but we *see* the speaker state something wrong about Python! Looks like they can't fix it (setting up the studio with the same decoration is undoable). Yes they could, should probably remove the section though. Looks like Al Sweigart got this guideline right in its scratch series if we want a good example. Best, ?--? Julien Palard https://mdk.fr? From al at inventwithpython.com Sun May 6 15:49:59 2018 From: al at inventwithpython.com (Al Sweigart) Date: Sun, 6 May 2018 12:49:59 -0700 Subject: [Doc-SIG] Video content in the standard library documentation In-Reply-To: References: Message-ID: I definitely agree will all of Julien's points. Having a face is distracting, makes editing harder, and dealing with lighting/makeup to look good on camera is a pain. Also, the videos should be a *maximum* of 6 minutes in length. Philip Guo (creator of pythontutor.com and a CS professor at Rochester) has a great article on engagement rates for online course videos. Even with the concerns about engagement aside, short videos are easier to make and keep up to date. Something else to consider: Do we need videos? We could also consider using a webpage with one of those https://trinket.io/ in-browser interactive shells (though the PSF probably doesn't want to play favorites with any company.) -Al On Sun, May 6, 2018 at 1:25 AM, Julien Palard via Doc-SIG < doc-sig at python.org> wrote: > > I was thinking of providing a set of templates and guidelines for having > ?5 minute overview? videos > > I propose this guideline: > > - Never show the face of someone speaking. > > Why? It allows to: > > - FIX a section of the sound track without re-recording the video track > (in case of a error, or to better phrase something). > - Translate the audio tracks of the videos without caring about lip sync > (I suspect non of us are willing to do lip sync). > > Why fixing is important? > > I know one (but won't public-shame) of a really great Python video, really > high video, studio, setup quality, video editing, ... all good, but we > *see* the speaker state something wrong about Python! Looks like they can't > fix it (setting up the studio with the same decoration is undoable). Yes > they could, should probably remove the section though. > > Looks like Al Sweigart got this guideline right in its scratch series if > we want a good example. > > Best, > ?-- > Julien Palard > https://mdk.fr? > > _______________________________________________ > Doc-SIG maillist - Doc-SIG at python.org > https://mail.python.org/mailman/listinfo/doc-sig > -------------- next part -------------- An HTML attachment was scrubbed... URL: From ncoghlan at gmail.com Sun May 6 21:31:30 2018 From: ncoghlan at gmail.com (Nick Coghlan) Date: Mon, 7 May 2018 11:31:30 +1000 Subject: [Doc-SIG] Video content in the standard library documentation In-Reply-To: References: Message-ID: On 7 May 2018 at 05:49, Al Sweigart wrote: > I definitely agree will all of Julien's points. Having a face is > distracting, makes editing harder, and dealing with lighting/makeup to look > good on camera is a pain. > > Also, the videos should be a *maximum* of 6 minutes in length. Philip Guo > (creator of pythontutor.com and a CS professor at Rochester) has a great > article on engagement rates for online course videos. Even with the > concerns about engagement aside, short videos are easier to make and keep > up to date. > > Something else to consider: Do we need videos? We could also consider > using a webpage with one of those https://trinket.io/ in-browser > interactive shells (though the PSF probably doesn't want to play favorites > with any company.) > The PSF doesn't tend to view that kind of thing as playing favourites - if we need to go beyond what a company offers in their baseline freemium accounts, then the PSF staff and/or Board may be able to help arrange an in-kind sponsorship, and set up a formal relationship with the vendor accordingly (e.g. PyPI relies heavily on in-kind sponsorships, and that gets recognised on https://www.python.org/psf/sponsorship/sponsors/). If it's possible to avoid videos, while still providing screencast-style content, that would be a good thing - while video playback on the web is vastly better than it used to be Cheers, Nick. P.S. Note also that the PSF has an existing technical relationship with PythonAnywhere to power the inline interactive shell in the carousel at the top of the python.org home page (click the yellow ">_" icon if you've never seen that in action). So if folks can think of ways that relationship could potentially be pursued further to help enhance the tutorial and other documentation, that would be a discussion well worth having :) -- Nick Coghlan | ncoghlan at gmail.com | Brisbane, Australia -------------- next part -------------- An HTML attachment was scrubbed... URL: From fromwheretowhere.service at gmail.com Fri May 11 12:40:29 2018 From: fromwheretowhere.service at gmail.com (Xuan Wu) Date: Fri, 11 May 2018 09:40:29 -0700 Subject: [Doc-SIG] readability of sample programs in tutorial Message-ID: Hi, when reading some of the sample codes in the official tutorial, I had to do research to understand the background of naming and string constants, like those strings from the script of Monty Python. Still this one in $5.5 is the most challenging so far: >>>tel = {'jack': 4098, 'sape': 4139} >>>tel['guido'] = 4127 >>>tel {'sape': 4139, 'guido': 4127, 'jack': 4098} >>>tel['jack'] 4098 ... I did quite some digging to confirm my guess of the hidden meaning, during which I realized it was initially written 27 years ago, without much change so far. Now I'm curious if its meaning is obvious to most nowadays beginners even as English speakers. In general, I wonder if there was discussion of revising some sample programs for better readability or adding more comments/introductory texts? Thanks. -------------- next part -------------- An HTML attachment was scrubbed... URL: From steve at pearwood.info Fri May 11 13:16:28 2018 From: steve at pearwood.info (Steven D'Aprano) Date: Sat, 12 May 2018 03:16:28 +1000 Subject: [Doc-SIG] readability of sample programs in tutorial In-Reply-To: References: Message-ID: <20180511171628.GA9562@ando.pearwood.info> On Fri, May 11, 2018 at 09:40:29AM -0700, Xuan Wu wrote: > >>>tel = {'jack': 4098, 'sape': 4139} > >>>tel['guido'] = 4127 > >>>tel > {'sape': 4139, 'guido': 4127, 'jack': 4098} > >>>tel['jack'] > 4098 ... > > I did quite some digging to confirm my guess of the hidden meaning, > during which I realized it was initially written 27 years ago, without > much change so far. Now I'm curious if its meaning is obvious to most > nowadays beginners even as English speakers. There's a hidden meaning? I thought they were just arbitrary keys and values. Obviously "guido" comes from the designer of Python, but I always thought that the rest are just arbitrary. -- Steve From fromwheretowhere.service at gmail.com Sat May 12 16:11:56 2018 From: fromwheretowhere.service at gmail.com (Xuan Wu) Date: Sat, 12 May 2018 13:11:56 -0700 Subject: [Doc-SIG] readability of sample programs in tutorial In-Reply-To: References: Message-ID: <11c0895a-2f1a-0f74-1949-0276a4985f91@gmail.com> Hi Steve, actually I suspected the same at the first sight, but after realizing "Guido" is the creator, I dug the python source code history and found out he actually drafted this sample himself around 1991. Then I found in his resume that: > From 1986 till 1991 I was with the Amoeba project, headed by Sape Mullender Sape's phone back then at CWI was |+20-592 4139. | After that I found another colleague of them is Jack Jansen, with phone 20 592 4098 And 20-592-4127 might be a shared phone number, as it was listed as overall contact number in some of CWI's publications, so likely Guido and Irv (not sure who that refers to, which bothers me a bit still, but I can live with it) both used that at some time, which is also shown in the sample program. So, 'tel' seems to be a sample telephone book of CWI, with only the last 4 digits. The program's meaning becomes obvious only after all this history study. It was fun for sure, but IMO most readers won't go that far, as I didn't find any of such explanations online so far. Best, Xuan. On 5/11/18 9:40 AM, Xuan Wu wrote: > > Hi, > > when reading some of the sample codes in the official tutorial, I had > to do research to understand the background of naming and string > constants, like those strings from the script of Monty Python. Still > this one in $5.5 is the most challenging so far: > > >>>tel = {'jack': 4098, 'sape': 4139} > >>>tel['guido'] = 4127 > >>>tel > {'sape': 4139, 'guido': 4127, 'jack': 4098} > >>>tel['jack'] > 4098 ... > > I did quite some digging to confirm my guess of the hidden meaning, > during which I realized it was initially written 27 years ago, without > much change so far. Now I'm curious if its meaning is obvious to most > nowadays beginners even as English speakers. > > In general, I wonder if there was discussion of revising some sample > programs for better readability or adding more comments/introductory > texts? > > Thanks. > -------------- next part -------------- An HTML attachment was scrubbed... URL: From julien at palard.fr Sun May 13 05:02:34 2018 From: julien at palard.fr (Julien Palard) Date: Sun, 13 May 2018 05:02:34 -0400 Subject: [Doc-SIG] readability of sample programs in tutorial In-Reply-To: <11c0895a-2f1a-0f74-1949-0276a4985f91@gmail.com> References: <11c0895a-2f1a-0f74-1949-0276a4985f91@gmail.com> Message-ID: Hi, On 12 May 2018 10:11 PM, Xuan Wu wrote: > The program's meaning becomes obvious only after all this history study. Yes, but don't forgot that this is not a program (demonstrating usefull behavior), but a sample, demonstrating syntax. > It was fun for sure, but IMO most readers won't go that far, as I didn't find any of such explanations online so far. Which is fine, as the example is OK to understand syntax. Understanding what authors had in mind back then while redacting examples is a whole other level of reading. PS: Good lunk understanding what the author of >>> words ['defenestrate', 'cat', 'window', 'defenestrate'] had in mind (yet it does not hurt readability of the example, IMHO). ?--? Julien Palard https://mdk.fr? From fromwheretowhere.service at gmail.com Mon May 14 16:04:08 2018 From: fromwheretowhere.service at gmail.com (Xuan Wu) Date: Mon, 14 May 2018 13:04:08 -0700 Subject: [Doc-SIG] readability of sample programs in tutorial In-Reply-To: References: <11c0895a-2f1a-0f74-1949-0276a4985f91@gmail.com> Message-ID: <21bb2709-f812-2a4b-ec1d-410044b87c2b@gmail.com> Hi, On 5/13/18 2:02 AM, Julien Palard wrote: > Hi, > > On 12 May 2018 10:11 PM, Xuan Wu wrote: >> The program's meaning becomes obvious only after all this history study. > Yes, but don't forgot that this is not a program (demonstrating usefull behavior), but a sample, demonstrating syntax. If the code is just demonstrating syntax, something like `dictionary = {'key1':1, 'key2':2}` would be sufficient and leave no room for speculation. That would also make the sample dry and boring, and reader would not learn which real-world use cases a dictionary is typically used in. IMO demonstrating the use case was part of the initial intention, so making the meaning of the use case as clear as possible would be ideal. > >> It was fun for sure, but IMO most readers won't go that far, as I didn't find any of such explanations online so far. > Which is fine, as the example is OK to understand syntax. Understanding what authors had in mind back then while redacting examples is a whole other level of reading. Frankly my investigation did not aim to understand what Guido had in mind, but to understand what this program was about, which I couldn't have figured out without knowing Guido's past. Like I mentioned, if it were clear that they were arbitrary values, I would have left it be without second thought. At this moment I don't think Guido intended to make the values arbitrary, otherwise he wouldn't have even put his name in it in the first place. My guess is he mainly targeted his colleagues as the first readers of the tutorial, who would easily understand its meaning back then. Though most current readers are fine without knowing all this background info and just treating those values as arbitrary, still I think it's a pity that the code's meaning was buried in history. IMO it'll be more reader-friendly to add footnotes to those classic sample code for better understanding, which the initial author would also appreciate. Best, Xuan. From adrianliaw2000 at gmail.com Fri May 25 04:30:59 2018 From: adrianliaw2000 at gmail.com (Adrian Liaw) Date: Fri, 25 May 2018 16:30:59 +0800 Subject: [Doc-SIG] Coordinating zh_TW (Taiwanese Mandarin) Translations Message-ID: Hi all, This is Adrian from Taiwan, I'm currently a core organising staff at PyCon TW, and I would like to volunteer as the coordinator of zh_TW (Taiwanese Mandarin) translations! The current translations (although it's not complete enough to add it to the language switcher) are hosted on our own GitHub repository ( https://github.com/python-doc-tw/cpython-tw/tree/tw-3.6/Doc/locale/zh_TW/LC_MESSAGES) and on our own Transifex project ( https://www.transifex.com/python-tw-doc/python-36-tw), and I would like to migrate them into the PEP 545 workflow. However, I have a concern here, if I migrate the translations to the official Transifex project for Python documentation translations, that way it may completely lost the metadata of each string including history and translator, which I think is probably a bad thing to happen. I'm wondering if anyone knows whether there's some way to solve this problem or it's currently an unsupported feature (migrating translation metadata along with the translations) on Transifex? Thank you for taking time reading this, thank you for your contributions, and I'm super excited about making more contributions to the Python community! Best Regards, Wey-Han "Adrian" Liaw -- Wey-Han "Adrian" Liaw (@adrianliaw) http://linkedin.com/in/adrianliaw -------------- next part -------------- An HTML attachment was scrubbed... URL: From songofacandy at gmail.com Sat May 26 09:54:04 2018 From: songofacandy at gmail.com (INADA Naoki) Date: Sat, 26 May 2018 22:54:04 +0900 Subject: [Doc-SIG] Coordinating zh_TW (Taiwanese Mandarin) Translations In-Reply-To: References: Message-ID: Migrating Transifex project is not mandatory. If you don't have any problem about current project, I recommend you to keep your project. On the other hand, you need to migrate Github repository. I don't know that "tw" is valid IETF language tag or not. If so, the repository name will be github.com/python/python-docs-tw Regards, On Sat, May 26, 2018 at 10:10 PM Adrian Liaw wrote: > Hi all, > This is Adrian from Taiwan, I'm currently a core organising staff at PyCon TW, and I would like to volunteer as the coordinator of zh_TW (Taiwanese Mandarin) translations! > The current translations (although it's not complete enough to add it to the language switcher) are hosted on our own GitHub repository ( https://github.com/python-doc-tw/cpython-tw/tree/tw-3.6/Doc/locale/zh_TW/LC_MESSAGES) and on our own Transifex project ( https://www.transifex.com/python-tw-doc/python-36-tw), and I would like to migrate them into the PEP 545 workflow. > However, I have a concern here, if I migrate the translations to the official Transifex project for Python documentation translations, that way it may completely lost the metadata of each string including history and translator, which I think is probably a bad thing to happen. I'm wondering if anyone knows whether there's some way to solve this problem or it's currently an unsupported feature (migrating translation metadata along with the translations) on Transifex? > Thank you for taking time reading this, thank you for your contributions, and I'm super excited about making more contributions to the Python community! > Best Regards, > Wey-Han "Adrian" Liaw > -- > Wey-Han "Adrian" Liaw (@adrianliaw) > http://linkedin.com/in/adrianliaw > _______________________________________________ > Doc-SIG maillist - Doc-SIG at python.org > https://mail.python.org/mailman/listinfo/doc-sig -- INADA Naoki From julien at palard.fr Sat May 26 09:50:42 2018 From: julien at palard.fr (Julien Palard) Date: Sat, 26 May 2018 09:50:42 -0400 Subject: [Doc-SIG] Coordinating zh_TW (Taiwanese Mandarin) Translations In-Reply-To: References: Message-ID: Hi Adrian, It's nice to get news from zh_TW! > This is Adrian from Taiwan, I'm currently a core organising staff at PyCon TW, and I would like to volunteer as the coordinator of zh_TW (Taiwanese Mandarin) translations! Having a coordinator for zh_TW would be great, and we do not have one... so welcome abord! > However, I have a concern here, if I migrate the translations to the official Transifex project for Python documentation translations The transifex project is not official, it may looks like official because almost everyone is using it, but it's not mandatory to use it. Every country is free to use their own tool to coordinate their translation, we do not make Transifex mandatory. > that way it may completely lost the metadata of each string including history and translator, which I think is probably a bad thing to happen. I'm wondering if anyone knows whether there's some way to solve this problem or it's currently an unsupported feature (migrating translation metadata along with the translations) on Transifex? I don't really know Transifex, but feel free to either ask them directy and/or stay in your own transifex organisation. > Thank you for taking time reading this, thank you for your contributions, and I'm super excited about making more contributions to the Python community! Thank you for contributing! Feel free to ask a repository on the cpython organization when you feel ready to migrate there. You'll have to use the same file hierarchy as other repos in order to have the docsbuild-scripts working with them, like : https://github.com/python/python-docs-fr or https://github.com/python/python-docs-ja. It means to have a branch per version you translate, you're free to maintain the versions you like, a single one is OK, the branch name have to be the version (like "3.6"), and .po" files in the root of the repository, with "gettext_compact=0". Feel free to copy or simply get inspiration from https://github.com/python/python-docs-fr/tree/3.6/Makefile to create the hierarchy / merge from upstream, sync with transifex (I use a local "transifex" branch to tx pull and tx push, the git to merge to/from the transifex branch). Bests, ?--? Julien Palard https://mdk.fr? From julien at palard.fr Sat May 26 10:13:56 2018 From: julien at palard.fr (Julien Palard) Date: Sat, 26 May 2018 10:13:56 -0400 Subject: [Doc-SIG] Coordinating zh_TW (Taiwanese Mandarin) Translations In-Reply-To: References: Message-ID: > I don't know that "tw" is valid IETF language tag or not. If so, the > repository name will be github.com/python/python-docs-tw "tw" is the language tag for Twi (https://en.wikipedia.org/wiki/Twi), we can't use it for this translation. "zh" is the language tag for Chinese, it can be followed by subtags. "TW" is the region subtag for Taiwan. So if "Chinese as spoken in Taiwan" is the language Adrian is translating, the repository will be named "python-docs-zh-tw". According to PEP 545 (and BCP-47) we should *not* use subtags if it does not add usefull information. Typically "fr-FR" "French as spoken in France" is kind of redundent and should be simplified "fr". So can we simplify "zh-tw" to "zh"? I don't think so, as there is another project, "zh-cn" (https://zhsj.github.io/python-docs-zh-cn/), but as I don't speak chinese, I think Adrian also have its word on it. ?--? Julien Palard https://mdk.fr? From zsj950618 at gmail.com Sat May 26 13:59:10 2018 From: zsj950618 at gmail.com (Shengjing Zhu) Date: Sun, 27 May 2018 01:59:10 +0800 Subject: [Doc-SIG] Coordinating zh_TW (Taiwanese Mandarin) Translations In-Reply-To: References: Message-ID: On Sat, May 26, 2018 at 10:14 PM Julien Palard via Doc-SIG < doc-sig at python.org> wrote: > So can we simplify "zh-tw" to "zh"? I don't think so, as there is another project, "zh-cn" (https://zhsj.github.io/python-docs-zh-cn/), but as I don't speak chinese, I think Adrian also have its word on it. Thanks for mentioning my repo. It's used for previewing the Chinese(China) translation on transifex[1]. There are Simplified Chinese and Traditional Chinese, the former is mostly used in China mainland and latter in Taiwan. It's complicated to indicate these two languages in RFC 5646. The formal should be zh-Hans-CN, and zh-Hant-TW. Because there's also zh-Hans-SG(Simplified Chinese used in Singapore)/zh-Hant-HK(Traditional Chinese used in Hongkong)/etc... You can see all the language tags beginning with zh- prefix in iana[2] However it's common to see zh-cn/zh-tw in various open source projects, especially in sphinx[3]. So I'd like to keep using zh-cn and zh-tw as I didn't see there's much translation effort in other varieties. BTW, for zh_CN translations, we are slow at reaching the coverage. However I've contacted Xiang Zhang(The only person I known using Chinese and also a core developer) to get the work organized. [1] https://www.transifex.com/python-doc/dashboard/all_projects/zh_CN/ [2] https://www.iana.org/assignments/language-subtag-registry/language-subtag-registry [3] https://github.com/sphinx-doc/sphinx/tree/master/sphinx/locale -- Regards, Shengjing Zhu From julien at palard.fr Sat May 26 14:08:31 2018 From: julien at palard.fr (Julien Palard) Date: Sat, 26 May 2018 14:08:31 -0400 Subject: [Doc-SIG] Coordinating zh_TW (Taiwanese Mandarin) Translations In-Reply-To: References: Message-ID: > So I'd like to keep using zh-cn and zh-tw as I didn't see there's much translation effort in other varieties. OK, works for me. And if in the future they start translating we'll still be able to affect them specific tags as needed, like zh-Hant-HK, we're not locking them out by choosing zh-cn and zh-tw. > BTW, for zh_CN translations, we are slow at reaching the coverage. However I've contacted Xiang Zhang(The only person I known using Chinese and also a > core developer) to get the work organized. Xiang Zhang told in january 2018 he won't be "as free as before" [1], already in a discussion about chinese translations : https://mail.python.org/pipermail/doc-sig/2018-January/003991.html. [1]: https://mail.python.org/pipermail/doc-sig/2018-January/003994.html ?--? Julien Palard https://mdk.fr? From adrianliaw2000 at gmail.com Sun May 27 08:38:15 2018 From: adrianliaw2000 at gmail.com (Adrian Liaw) Date: Sun, 27 May 2018 20:38:15 +0800 Subject: [Doc-SIG] Coordinating zh_TW (Taiwanese Mandarin) Translations In-Reply-To: References: Message-ID: Thanks everyone for your great comments and all the useful informations. I'd say I'm agreeing with using zh-tw language tag. And I personally believe adding "Hant" or "Hans" tag is somehow redundant, the reason is that you can usually assume its writing system by region. e.g. you can assume zh-cn to be written in Simplified Chinese, zh-tw to be in Traditional Chinese, zh-hk (Hong Kong Cantonese) to be in Traditional Chinese, zh-sg (Singaporean Mandarin) to be in Simplified Chinese, etc. Regarding the repository setup that Julien mentioned earlier, big thanks to Julien for providing lots of inspirations, I'll stay with our own Transifex project, and I'll setup the project and a proper contribution workflow, I'll get back to you as soon as I done it! Best Regards, Adrian On Sun, 27 May 2018 at 02:08 Julien Palard via Doc-SIG wrote: > > So I'd like to keep using zh-cn and zh-tw as I didn't see there's much > translation effort in other varieties. > > OK, works for me. And if in the future they start translating we'll still > be able to affect them specific tags as needed, like zh-Hant-HK, we're not > locking them out by choosing zh-cn and zh-tw. > > > BTW, for zh_CN translations, we are slow at reaching the coverage. > However I've contacted Xiang Zhang(The only person I known using Chinese > and also a > > core developer) to get the work organized. > > Xiang Zhang told in january 2018 he won't be "as free as before" [1], > already in a discussion about chinese translations : > https://mail.python.org/pipermail/doc-sig/2018-January/003991.html. > > [1]: https://mail.python.org/pipermail/doc-sig/2018-January/003994.html > > ?-- > Julien Palard > https://mdk.fr? > > _______________________________________________ > Doc-SIG maillist - Doc-SIG at python.org > https://mail.python.org/mailman/listinfo/doc-sig > -- Wey-Han "Adrian" Liaw (@adrianliaw) http://linkedin.com/in/adrianliaw -------------- next part -------------- An HTML attachment was scrubbed... URL: